mirror of
https://github.com/pezkuwichain/pezkuwi-subxt.git
synced 2026-06-13 07:01:05 +00:00
Markdown linter (#1309)
* Add markdown linting - add linter default rules - adapt rules to current code - fix the code for linting to pass - add CI check fix #1243 * Fix markdown for Substrate * Fix tooling install * Fix workflow * Add documentation * Remove trailing spaces * Update .github/.markdownlint.yaml Co-authored-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io> * Fix mangled markdown/lists * Fix captalization issues on known words
This commit is contained in:
Chevdor
@@ -5,7 +5,7 @@ All notable changes to this project will be documented in this file.
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
The semantic versioning guarantees cover the interface to the substrate runtime which
|
||||
The semantic versioning guarantees cover the interface to the Substrate runtime which
|
||||
includes this pallet as a dependency. This module will also add storage migrations whenever
|
||||
changes require it. Stability with regard to offchain tooling is explicitly excluded from
|
||||
this guarantee: For example adding a new field to an in-storage data structure will require
|
||||
|
||||
@@ -9,66 +9,68 @@ The Contracts module provides functionality for the runtime to deploy and execut
|
||||
|
||||
## 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 [`frame_support::traits::fungible`]. These "smart-contract accounts"
|
||||
have the ability to instantiate smart-contracts and make calls to other contract and non-contract accounts.
|
||||
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 [`frame_support::traits::fungible`].
|
||||
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 `code_hash`.
|
||||
This means that multiple smart-contracts can be instantiated from the same `code`, without replicating
|
||||
the code each time.
|
||||
The smart-contract code is stored once, and later retrievable via its `code_hash`. This means that multiple
|
||||
smart-contracts can be instantiated from the same `code`, 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.
|
||||
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.
|
||||
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`](https://paritytech.github.io/substrate/master/sp_weights/struct.Weight.html) 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.
|
||||
Senders must specify a [`Weight`](https://paritytech.github.io/substrate/master/sp_weights/struct.Weight.html) 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 weight 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.
|
||||
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 weight 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 `ref_time` `Weight` is defined as one picosecond of execution time on the runtime's reference machine.
|
||||
|
||||
### Revert Behaviour
|
||||
|
||||
Contract call failures are not 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.
|
||||
Contract call failures are not 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.
|
||||
|
||||
### Off-chain Execution
|
||||
|
||||
In general, a contract execution needs to be deterministic so that all nodes come to the same
|
||||
conclusion when executing it. To that end we disallow any instructions that could cause
|
||||
indeterminism. Most notable are any floating point arithmetic. That said, sometimes contracts
|
||||
are executed off-chain and hence are not subject to consensus. If code is only executed by a
|
||||
single node and implicitly trusted by other actors is such a case. Trusted execution environments
|
||||
come to mind. To that end we allow the execution of indeterminstic code for off-chain usages
|
||||
with the following constraints:
|
||||
In general, a contract execution needs to be deterministic so that all nodes come to the same conclusion when executing
|
||||
it. To that end we disallow any instructions that could cause indeterminism. Most notable are any floating point
|
||||
arithmetic. That said, sometimes contracts are executed off-chain and hence are not subject to consensus. If code is
|
||||
only executed by a single node and implicitly trusted by other actors is such a case. Trusted execution environments
|
||||
come to mind. To that end we allow the execution of indeterminstic code for off-chain usages with the following
|
||||
constraints:
|
||||
|
||||
1. No contract can ever be instantiated from an indeterministic code. The only way to execute
|
||||
the code is to use a delegate call from a deterministic contract.
|
||||
2. The code that wants to use this feature needs to depend on `pallet-contracts` and use [`bare_call()`](https://paritytech.github.io/substrate/master/pallet_contracts/pallet/struct.Pallet.html#method.bare_call)
|
||||
1. No contract can ever be instantiated from an indeterministic code. The only way to execute the code is to use a
|
||||
delegate call from a deterministic contract.
|
||||
2. The code that wants to use this feature needs to depend on `pallet-contracts` and use
|
||||
[`bare_call()`](https://paritytech.github.io/substrate/master/pallet_contracts/pallet/struct.Pallet.html#method.bare_call)
|
||||
directly. This makes sure that by default `pallet-contracts` does not expose any indeterminism.
|
||||
|
||||
#### How to use
|
||||
|
||||
An indeterministic code can be deployed on-chain by passing `Determinism::Relaxed`
|
||||
to [`upload_code()`](https://paritytech.github.io/substrate/master/pallet_contracts/pallet/struct.Pallet.html#method.upload_code). A deterministic contract can then delegate call into it if and only if it
|
||||
is ran by using [`bare_call()`](https://paritytech.github.io/substrate/master/pallet_contracts/pallet/struct.Pallet.html#method.bare_call) and passing [`Determinism::Relaxed`](https://paritytech.github.io/substrate/master/pallet_contracts/enum.Determinism.html#variant.Relaxed) to it. **Never use
|
||||
this argument when the contract is called from an on-chain transaction.**
|
||||
An indeterministic code can be deployed on-chain by passing `Determinism::Relaxed` to
|
||||
[`upload_code()`](https://paritytech.github.io/substrate/master/pallet_contracts/pallet/struct.Pallet.html#method.upload_code).
|
||||
A deterministic contract can then delegate call into it if and only if it is ran by using
|
||||
[`bare_call()`](https://paritytech.github.io/substrate/master/pallet_contracts/pallet/struct.Pallet.html#method.bare_call)
|
||||
and passing
|
||||
[`Determinism::Relaxed`](https://paritytech.github.io/substrate/master/pallet_contracts/enum.Determinism.html#variant.Relaxed)
|
||||
to it. **Never use this argument when the contract is called from an on-chain transaction.**
|
||||
|
||||
## Interface
|
||||
|
||||
### Dispatchable functions
|
||||
|
||||
Those are documented in the [reference documentation](https://paritytech.github.io/substrate/master/pallet_contracts/index.html#dispatchable-functions).
|
||||
Those are documented in the [reference
|
||||
documentation](https://paritytech.github.io/substrate/master/pallet_contracts/index.html#dispatchable-functions).
|
||||
|
||||
### Interface exposed to contracts
|
||||
|
||||
@@ -99,43 +101,43 @@ The documentation of all importable functions can be found
|
||||
|
||||
## Usage
|
||||
|
||||
This module executes WebAssembly smart contracts. These can potentially be written in any language
|
||||
that compiles to Wasm. However, using a language that specifically targets this module
|
||||
will make things a lot easier. One such language is [`ink!`](https://use.ink). It enables
|
||||
writing WebAssembly-based smart-contracts in the Rust programming language.
|
||||
This module executes WebAssembly smart contracts. These can potentially be written in any language that compiles to
|
||||
Wasm. However, using a language that specifically targets this module will make things a lot easier. One such language
|
||||
is [`ink!`](https://use.ink). It enables writing WebAssembly-based smart-contracts in the Rust programming language.
|
||||
|
||||
## Debugging
|
||||
|
||||
Contracts can emit messages to the client when called as RPC through the [`debug_message`](https://paritytech.github.io/substrate/master/pallet_contracts/api_doc/trait.Current.html#tymethod.debug_message)
|
||||
Contracts can emit messages to the client when called as RPC through the
|
||||
[`debug_message`](https://paritytech.github.io/substrate/master/pallet_contracts/api_doc/trait.Current.html#tymethod.debug_message)
|
||||
API. This is exposed in [ink!](https://use.ink) via
|
||||
[`ink_env::debug_message()`](https://paritytech.github.io/ink/ink_env/fn.debug_message.html).
|
||||
|
||||
Those messages are gathered into an internal buffer and sent to the RPC client.
|
||||
It is up the the individual client if and how those messages are presented to the user.
|
||||
Those messages are gathered into an internal buffer and sent to the RPC client. It is up the the individual client if
|
||||
and how those messages are presented to the user.
|
||||
|
||||
This buffer is also printed as a debug message. In order to see these messages on the node
|
||||
console the log level for the `runtime::contracts` target needs to be raised to at least
|
||||
the `debug` level. However, those messages are easy to overlook because of the noise generated
|
||||
by block production. A good starting point for observing them on the console is using this
|
||||
command line in the root directory of the substrate repository:
|
||||
This buffer is also printed as a debug message. In order to see these messages on the node console the log level for the
|
||||
`runtime::contracts` target needs to be raised to at least the `debug` level. However, those messages are easy to
|
||||
overlook because of the noise generated by block production. A good starting point for observing them on the console is
|
||||
using this command line in the root directory of the Substrate repository:
|
||||
|
||||
```bash
|
||||
cargo run --release -- --dev -lerror,runtime::contracts=debug
|
||||
```
|
||||
|
||||
This raises the log level of `runtime::contracts` to `debug` and all other targets
|
||||
to `error` in order to prevent them from spamming the console.
|
||||
This raises the log level of `runtime::contracts` to `debug` and all other targets to `error` in order to prevent them
|
||||
from spamming the console.
|
||||
|
||||
`--dev`: Use a dev chain spec
|
||||
`--tmp`: Use temporary storage for chain data (the chain state is deleted on exit)
|
||||
`--dev`: Use a dev chain spec `--tmp`: Use temporary storage for chain data (the chain state is deleted on exit)
|
||||
|
||||
## Host function tracing
|
||||
|
||||
For contract authors, it can be a helpful debugging tool to see which host functions are called, with which arguments, and what the result was.
|
||||
For contract authors, it can be a helpful debugging tool to see which host functions are called, with which arguments,
|
||||
and what the result was.
|
||||
|
||||
In order to see these messages on the node console, the log level for the `runtime::contracts::strace` target needs to be raised to the `trace` level.
|
||||
In order to see these messages on the node console, the log level for the `runtime::contracts::strace` target needs to
|
||||
be raised to the `trace` level.
|
||||
|
||||
Example:
|
||||
Example:
|
||||
|
||||
```bash
|
||||
cargo run --release -- --dev -lerror,runtime::contracts::strace=trace,runtime::contracts=debug
|
||||
@@ -143,18 +145,16 @@ cargo run --release -- --dev -lerror,runtime::contracts::strace=trace,runtime::c
|
||||
|
||||
## Unstable Interfaces
|
||||
|
||||
Driven by the desire to have an iterative approach in developing new contract interfaces
|
||||
this pallet contains the concept of an unstable interface. Akin to the rust nightly compiler
|
||||
it allows us to add new interfaces but mark them as unstable so that contract languages can
|
||||
experiment with them and give feedback before we stabilize those.
|
||||
Driven by the desire to have an iterative approach in developing new contract interfaces this pallet contains the
|
||||
concept of an unstable interface. Akin to the rust nightly compiler it allows us to add new interfaces but mark them as
|
||||
unstable so that contract languages can experiment with them and give feedback before we stabilize those.
|
||||
|
||||
In order to access interfaces marked as `#[unstable]` in [`runtime.rs`](src/wasm/runtime.rs) one need to set
|
||||
`pallet_contracts::Config::UnsafeUnstableInterface` to `ConstU32<true>`. **It should be obvious
|
||||
that any production runtime should never be compiled with this feature: In addition to be
|
||||
subject to change or removal those interfaces might not have proper weights associated with
|
||||
them and are therefore considered unsafe**.
|
||||
`pallet_contracts::Config::UnsafeUnstableInterface` to `ConstU32<true>`. **It should be obvious that any production
|
||||
runtime should never be compiled with this feature: In addition to be subject to change or removal those interfaces
|
||||
might not have proper weights associated with them and are therefore considered unsafe**.
|
||||
|
||||
New interfaces are generally added as unstable and might go through several iterations
|
||||
before they are promoted to a stable interface.
|
||||
New interfaces are generally added as unstable and might go through several iterations before they are promoted to a
|
||||
stable interface.
|
||||
|
||||
License: Apache-2.0
|
||||
|
||||
@@ -1,9 +1,8 @@
|
||||
# Benchmarks
|
||||
|
||||
This directory contains real world ([ink!](https://use.ink), [solang](https://github.com/hyperledger/solang)) contracts which are used in macro benchmarks.
|
||||
Those benchmarks are not used to determine weights but rather to compare different contract
|
||||
languages and execution engines with larger wasm modules.
|
||||
|
||||
Files in this directory are used by `#[extra]` benchmarks in `src/benchmarking`. The json
|
||||
files are for informational purposes only and are not consumed by the benchmarks.
|
||||
This directory contains real world ([ink!](https://use.ink), [solang](https://github.com/hyperledger/solang)) contracts
|
||||
which are used in macro benchmarks. Those benchmarks are not used to determine weights but rather to compare different
|
||||
contract languages and execution engines with larger wasm modules.
|
||||
|
||||
Files in this directory are used by `#[extra]` benchmarks in `src/benchmarking`. The json files are for informational
|
||||
purposes only and are not consumed by the benchmarks.
|
||||
|
||||
@@ -1,3 +1,3 @@
|
||||
A crate that hosts a common definitions that are relevant for the pallet-contracts.
|
||||
|
||||
License: Apache-2.0
|
||||
License: Apache-2.0
|
||||
|
||||
Reference in New Issue
Block a user