Merge branch 'master' into gn/ce-use-result-macro

.github/dependabot.yml

@@ -4,14 +4,14 @@ updates:
     directory: "/"
     schedule:
       interval: "daily"
+    # ignore Substrate pallets major updates.
+    # automated Substrate releases cause dependabot PR spam, so these must be updated manually when required.
+    ignore:
+      - dependency-name: "sp-*"
+        update-types: [ "version-update:semver-major" ]
+      - dependency-name: "pallet-*"
+        update-types: [ "version-update:semver-major" ]
   - package-ecosystem: github-actions
     directory: '/'
     schedule:
       interval: daily
-  - ignore:
-    - dependency-name: sp-*
-      versions:
-      - ">= 0"
-    - dependency-name: pallet-*
-      versions:
-      - ">= 0"

.gitlab-ci.yml

@@ -29,7 +29,7 @@ variables:
   # CI_IMAGE is changed to "-:staging" when the CI image gets rebuilt
   # read more https://github.com/paritytech/scripts/pull/244
   CI_IMAGE:                        "paritytech/ink-ci-linux:production"
-  PURELY_STD_CRATES:               "ink/codegen metadata engine"
+  PURELY_STD_CRATES:               "ink/codegen metadata engine e2e e2e/macro"
   ALSO_WASM_CRATES:                "env storage storage/traits allocator prelude primitives ink ink/macro ink/ir"
   ALL_CRATES:                      "${PURELY_STD_CRATES} ${ALSO_WASM_CRATES}"
   DELEGATOR_SUBCONTRACTS:          "accumulator adder subber"
@@ -311,6 +311,8 @@ docs:
     - cargo doc --no-deps --all-features -p ink_ir
     - cargo doc --no-deps --all-features -p ink_codegen
     - cargo doc --no-deps --all-features -p ink_metadata
+    - cargo doc --no-deps --all-features -p ink_e2e
+    - cargo doc --no-deps --all-features -p ink_e2e_macro
     - mv ${CARGO_TARGET_DIR}/doc ./crate-docs
     # FIXME: remove me after CI image gets nonroot
     - chown -R nonroot:nonroot ./crate-docs

ARCHITECTURE.md

@@ -19,9 +19,6 @@ ink! is composed of a number of crates that are all found in the
   The ink! language itself.
 * [`allocator`](https://github.com/paritytech/ink/tree/master/crates/allocator):
   The allocator used for dynamic memory allocation in a contract.
-* [`engine`](https://github.com/paritytech/ink/tree/master/crates/engine):
-  An off-chain testing engine, it simulates a blockchain environment and allows
-  mocking specified conditions.
 * [`env`](https://github.com/paritytech/ink/tree/master/crates/env):
   Serves two roles:
   * Exposes environmental functions, like information about the caller
@@ -44,6 +41,15 @@ ink! is composed of a number of crates that are all found in the
 * [`storage`](https://github.com/paritytech/ink/tree/master/crates/prelude):
   The collections that are available for contract developers to put in
   a smart contracts storage.
+* [`engine`](https://github.com/paritytech/ink/tree/master/crates/engine):
+  An off-chain testing engine, it simulates a blockchain environment and allows
+  mocking specified conditions.
+* [`e2e`](https://github.com/paritytech/ink/tree/master/crates/e2e):
+  An end-to-end testing framework for ink! contracts. It requires a Substrate node
+  which includes `pallet-contracts` running in the background. The crate provides a
+  macro which can be used
+  to write an idiomatic Rust test that will in the background create transactions,
+  submit it to the Substrate chain and return the state changes, gas costs, etc.
 
 An important thing to note is that the crates are primarily run in
 a `no_std` environment.
@@ -96,14 +102,27 @@ gas costs) and a lower transaction throughput. Freeing memory is
 irrelevant for our use-case anyway, as the entire memory instance
 is set up fresh for each individual contract call anyway.
 
-## Nightly Rust features in ink!
+## Unstable Rust features in ink!
 
-We would like to get away from nightly features of Rust in ink!, so
+We would like to get away from unstable features of Rust in ink!, so
 that users can just use stable Rust for building their contracts.
 At the moment we're still stuck with one nightly feature though:
 [alloc_error_handler](https://github.com/rust-lang/rust/issues/51540).
 It's needed because we use a specialized memory allocation handler,
 the `ink_allocator` crate.
+It's unclear when or if this feature will ever make it to stable.
+
+We had a lot of issues when requiring users to use Rust nightly. Mostly
+because there were regularly bugs in the nightly Rust compiler that
+often took days to be fixed.
+As a consequence we decided on having `cargo-contract` `v2.0.0` run
+`cargo +stable build` with `RUSTC_BOOTSTRAP=1`. This is kind of a hack,
+the env variable enables unstable features in the stable Rust toolchain.
+But it enabled us to switch tutorials/guides to Rust stable.
+
+One advantage is that users don't deal with an ever-changing nightly
+compiler. It's easier for us to support. If you build a contract without
+`cargo-contract` you will have to set this env variable too or use nightly.
 
 ## Interaction with `pallet-contracts`
 
@@ -170,3 +189,35 @@ one point.
 
 The prefix `seal` here is for historic reasons. There is some analogy to sealing a
 contract. And we found seals to be a cute animal as well ‒ like squids!
+
+## `Environment` Trait
+
+You can use ink! on any blockchain that was built with the [Substrate](https://substrate.io)
+framework and includes the [`pallet-contracts`](https://github.com/paritytech/substrate/tree/master/frame/contracts)
+module.
+Substrate does not define specific types for a blockchain, it uses
+generic types throughout.
+Chains built on Substrate can decide on their own which types they want
+to use for e.g. the chain's block number or account id's. For example,
+chains that intend to be compatible to Ethereum typically use the same
+type as Ethereum for their `AccountId`.
+
+The `Environment` trait is how ink! knows the concretes types of the chain
+to which the contract will be deployed to.
+Specifically, our `ink_env` crate defines a trait [`Environment`](https://paritytech.github.io/ink/ink_env/trait.Environment.html)
+which specifies the types.
+By default, ink! uses the default Substrate types, the `ink_env` crate
+exports an implementation of the `Environment` trait for that:
+[`DefaultEnvironment`](https://paritytech.github.io/ink/ink_env/enum.DefaultEnvironment.html).
+
+If you are developing for a chain that uses different types than the
+Substrate default types you can configure a different environment in
+the contract macro ([documentation here](https://paritytech.github.io/ink/ink/attr.contract.html#header-arguments)):
+
+```rust
+#[ink::contract(env = MyCustomTypes)]
+```
+
+__Important:__ If a developer writes a contract for a chain that deviates
+from the default Substrate types, they have to make sure to use that
+chain's `Environment`.

CHANGELOG.md

@@ -7,8 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## Unreleased
 - Add E2E testing framework MVP ‒ [#1395](https://github.com/paritytech/ink/pull/1395)
 - Add E2E tests for `Mapping` functions - [#1492](https://github.com/paritytech/ink/pull/1492)
+- Make CallBuilder and CreateBuilder error handling optional - [#1602](https://github.com/paritytech/ink/pull/1602)
+- Rename `CallBuilder::fire()` method to `invoke()` - [#1604](https://github.com/paritytech/ink/pull/1604)
 - Chain Extension: Evaluation of method return type at compile time - [#1569](https://github.com/paritytech/ink/pull/1569).
-  This PR introduces breaking changes to chain extension macro API: **`returns_result` flag has been removed**.
+
+### Breaking Changes
+With this release there are three breaking changes related to the `CallBuilder`
+`CreateBuilder` and the Chain Extension API.
+
+1. The `invoke()` methods now unwrap the `Result` from `pallet-contracts` under the hood
+   ([#1602](https://github.com/paritytech/ink/pull/1602)).
+   If you wish to handle the error use the new `try_` variants of those methods instead.
+1. The `CallBuilder::fire()` method has been renamed to `invoke()`
+   ([#1604](https://github.com/paritytech/ink/pull/1604))
+1. The `returns_result` flag has been removed from the `#[ink(extension = …)]` attribute
+   ([#1569](https://github.com/paritytech/ink/pull/1569)).
+   We now infer this information at compile time. If `handle_status` is set to `true`,
+   the return type will still be wrapped into `Result` as before.
 
 ## Version 4.0.0-beta
 

README.md

@@ -23,7 +23,7 @@
 [j1]: https://img.shields.io/badge/click-blue.svg
 [j2]: https://paritytech.github.io/ink/ink
 [k1]: https://img.shields.io/badge/matrix-chat-brightgreen.svg?style=flat
-[k2]: https://riot.im/app/#/room/#ink:matrix.parity.io
+[k2]: https://app.element.io/#/room/#ink:matrix.parity.io
 [l1]: https://img.shields.io/discord/722223075629727774?style=flat-square&label=discord
 [l2]: https://discord.com/invite/wGUDt2p
 [s1]: https://img.shields.io/badge/click-white.svg?logo=StackExchange&label=ink!%20Support%20on%20StackExchange&labelColor=white&color=blue
@@ -74,7 +74,7 @@ It's a simple Substrate blockchain which includes the Substrate module for smart
 
 We also have a live testnet on [Rococo](https://github.com/paritytech/cumulus/#rococo-). Rococo is a Substrate based
 parachain which supports ink! smart contracts. For further instructions on using this
-testnet, follow the instructions in the
+testnet, follow the instructions in
 [our documentation](https://use.ink/testnet).
 
 For both types of chains the [Contracts UI](https://contracts-ui.substrate.io/)
@@ -109,7 +109,7 @@ In order to build the contract just execute this command in the `flipper` folder
 cargo +nightly contract build
 ```
 
-As a result you'll get a file `target/flipper.wasm` file, a `metadata.json` file and a `<contract-name>.contract` file in the `target` folder of your contract.
+As a result you'll get a `target/flipper.wasm` file, a `metadata.json` file and a `<contract-name>.contract` file in the `target` folder of your contract.
 The `.contract` file combines the Wasm and metadata into one file and needs to be used when instantiating the contract.
 
 
@@ -175,12 +175,12 @@ mod flipper {
 ```
 
 The [`flipper/src/lib.rs`](https://github.com/paritytech/ink/blob/master/examples/flipper/lib.rs)
-file in our examples folder contains exactly this code. Run `cargo contract build` to build your
+file in our examples folder contains exactly this code. Run `cargo +nightly contract build` to build your
 first ink! smart contract.
 
 ## Examples
 
-In the `examples` folder you'll find a number of examples written in ink!.
+In the [`examples`](https://github.com/paritytech/ink/tree/master/examples) folder you'll find a number of examples written in ink!.
 
 Some of the most interesting ones:
 
@@ -192,7 +192,7 @@ Some of the most interesting ones:
 
 To build a single example navigate to the root of the example and run:
 ```
-cargo contract build
+cargo contract +nightly build
 ```
 
 You should now have an `<name>.contract` file in the `target` folder of the contract.
@@ -208,7 +208,7 @@ This module is called the `contracts` pallet,
 * The `contracts` pallet requires smart contracts to be uploaded to the blockchain as a Wasm blob.
 * ink! is a smart contract language which targets the API exposed by `contracts`.
 Hence ink! contracts are compiled to Wasm.
-* When executing `cargo contract build` an additional file `metadata.json` is created.
+* When executing `cargo contract +nightly build` an additional file `metadata.json` is created.
 It contains information about e.g. what methods the contract provides for others to call.
 
 ## ink! Macros & Attributes Overview
@@ -224,7 +224,7 @@ In a module annotated with `#[ink::contract]` these attributes are available:
 | `#[ink(constructor)]` | Applicable to method. | Flags a method for the ink! storage struct as constructor making it available to the API for instantiating the contract. |
 | `#[ink(event)]` | On `struct` definitions. | Defines an ink! event. A contract can define multiple such ink! events. |
 | `#[ink(anonymous)]` | Applicable to ink! events. | Tells the ink! codegen to treat the ink! event as anonymous which omits the event signature as topic upon emitting. Very similar to anonymous events in Solidity. |
-| `#[ink(topic)]` | Applicable on ink! event field. | Tells the ink! codegen to provide a topic hash for the given field. Every ink! event can only have a limited number of such topic field. Similar semantics as to indexed event arguments in Solidity. |
+| `#[ink(topic)]` | Applicable on ink! event field. | Tells the ink! codegen to provide a topic hash for the given field. Every ink! event can only have a limited number of such topic fields. Similar semantics as to indexed event arguments in Solidity. |
 | `#[ink(payable)]` | Applicable to ink! messages. | Allows receiving value as part of the call of the ink! message. ink! constructors are implicitly payable. |
 | `#[ink(selector = S:u32)]` | Applicable to ink! messages and ink! constructors. | Specifies a concrete dispatch selector for the flagged entity. This allows a contract author to precisely control the selectors of their APIs making it possible to rename their API without breakage. |
 | `#[ink(selector = _)]` | Applicable to ink! messages. | Specifies a fallback message that is invoked if no other ink! message matches a selector. |

SECURITY.md

@@ -0,0 +1,9 @@
+# Reporting a vulnerability
+
+If you find something that can be treated as a security vulnerability, please do not use the issue tracker or discuss it in the public forum/channels, as it can cause more damage rather than giving real help to the ecosystem.
+
+Security vulnerabilities should be reported using [this contact form](https://security-submission.parity.io/).
+
+If you think that your report might be eligible for the Bug Bounty Program, please mark this during the submission. Please check up-to-date [Parity Bug Bounty Program rules](https://www.parity.io/bug-bounty) for more information about our Bug Bounty Program.
+
+**Warning:** This is an unified `SECURITY.md` file for the Paritytech GitHub Organization. The presence of this file does not mean that this repository is covered by the Bug Bounty program. Please always check the Bug Bounty Program scope for the information.

crates/e2e/Cargo.toml

@@ -21,7 +21,7 @@ ink = { version = "4.0.0-beta", path = "../ink" }
 ink_env = { version = "4.0.0-beta", path = "../env" }
 ink_primitives = { version = "4.0.0-beta", path = "../primitives" }
 
-contract-metadata = { version = "2.0.0-beta.1" }
+contract-metadata = { version = "2.0.0-rc" }
 impl-serde = { version = "0.3.1", default-features = false }
 jsonrpsee = { version = "0.16.0", features = ["ws-client"] }
 serde = { version = "1.0.137", default-features = false, features = ["derive"] }

crates/e2e/src/builders.rs

@@ -32,24 +32,28 @@ use scale::Encode;
 
 /// The type returned from `ContractRef` constructors, partially initialized with the execution
 /// input arguments.
-pub type CreateBuilderPartial<E, Args, R> = CreateBuilder<
+pub type CreateBuilderPartial<E, ContractRef, Args, R> = CreateBuilder<
     E,
+    ContractRef,
     Unset<<E as Environment>::Hash>,
     Unset<u64>,
     Unset<<E as Environment>::Balance>,
     Set<ExecutionInput<Args>>,
     Unset<ink_env::call::state::Salt>,
-    R,
+    Set<ReturnType<R>>,
 >;
 
 /// Get the encoded constructor arguments from the partially initialized `CreateBuilder`
-pub fn constructor_exec_input<E: Environment, Args: Encode, R>(
-    builder: CreateBuilderPartial<E, Args, R>,
-) -> Vec<u8> {
+pub fn constructor_exec_input<E, ContractRef, Args: Encode, R>(
+    builder: CreateBuilderPartial<E, ContractRef, Args, R>,
+) -> Vec<u8>
+where
+    E: Environment,
+{
     // set all the other properties to default values, we only require the `exec_input`.
     builder
         .endowment(0u32.into())
-        .code_hash(ink_primitives::Clear::clear())
+        .code_hash(ink_primitives::Clear::CLEAR_HASH)
         .salt_bytes(Vec::new())
         .params()
         .exec_input()