Verifiable builds section (#279)

* Verifiable builds section

* Update docs/basics/verification/contract-verification.md

Co-authored-by: Michael Müller <[email protected]>

* Update docs/basics/verification/contract-verification.md

Co-authored-by: Michael Müller <[email protected]>

* Update docs/basics/verification/contract-verification.md

Co-authored-by: Michael Müller <[email protected]>

* Update docs/basics/verification/contract-verification.md

Co-authored-by: Michael Müller <[email protected]>

* Apply suggestions from code review

Co-authored-by: Michael Müller <[email protected]>

* add note about supported version

---------

Co-authored-by: Michael Müller <[email protected]>

docs/basics/verification/contract-verification.md

@@ -0,0 +1,121 @@
+---
+title: Contract Verification
+slug: /basics/verification/contract-verification
+hide_title: true
+---
+
+<img src="/img/title/magnifying-glass.svg" className="titlePic" />
+
+# Contract Verification
+
+Contract verification is the process of matching a deployed ink! contract 
+with the source code and metadata generated when it was built. 
+
+The verification process for Rust-based smart contract languages is more
+complex than EVM-based languages such as Solidity due to the Rust 
+compiler not providing deterministic builds of contracts. 
+
+In order to verify an ink! smart contract, the verification
+process must recompile the contract in an identical host environment to
+which it was originally built. The simplest way to do this is using a Docker
+container.
+
+Since ink! `4.0.0`, `cargo-contract` provides the necessary tools to produce 
+a verifiable build and verify a binary against the reference contract.
+
+:::note
+Contract verification tools are currently available in `cargo-contract`
+version `4.0.0-alpha`. To install it, run
+```
+cargo install cargo-contract --locked --version 4.0.0-alpha
+```
+:::
+
+## Verifiable build
+
+As mentioned earlier, due to the non-deterministic nature of Rust compilation,
+smart contract developers are advised to build their project inside
+a Docker container we provide. Luckily, `cargo contract build`
+provides the `--verifiable` flag for this purpose.
+
+The steps for the verifiable build production are:
+1. [Install Docker Engine](https://docs.docker.com/engine/install/)
+2. (Linux users) Make sure you complete the [post-installation step](https://docs.docker.com/engine/install/linux-postinstall/).
+This is required for the correct operation of the command.
+4. Ensure Docker Engine is up and running, and the socket is accessible.
+3. Simply run `cargo contract build --verifiable`.
+
+This will pull the image with the version that corresponds to your `cargo-contract` crate version,
+perform a build, and write artifacts in the standard output directory.
+
+If everything is correct, you can verify the image version in the metadata file.
+It should contain a key-value `image` after the `contract` information:
+```json
+  "contract": {
+    "name": "flipper",
+    "version": "4.3.0",
+    "authors": [
+      "Parity Technologies <[email protected]>"
+    ]
+  },
+  "image": "paritytech/contracts-verifiable:4.0.0-alpha",
+```
+
+You are now ready to deploy your contract to a production chain.
+
+:::note
+The image is `amd64` based. Therefore, the build times can be significantly slower
+on Apple Silicon machines. To overcome the issue enable _Rosetta for x86/amd64 emulation_ 
+in _Settings_ → _Features in development_ tab in Docker Desktop App.
+:::
+
+## Verifying contract
+
+Similarly to etherscan, you want to ensure that the given contract bundle
+is indeed a copy of some well-known contract code.
+
+There are two options when it comes to verification:
+* Local bare-bones verification using `cargo contract verify`
+* A third-party service [Sirato](/basics/verification/sirato)
+
+`cargo contract verify` allows you to verify the given cargo project
+against a reference contract bundle. 
+
+Simply run `cargo contract verify --contract <path>` 
+in the cargo project directory. 
+
+If the reference contract was not build inside a docker container, the command
+will compare the build info from the reference contract with the current environment
+to ensure a match in environment.
+
+:::warning
+If you are not using standardized verifiable builds. It is your responsibility
+to ensure deterministic environment both for build and verification of 
+smart contracts.
+:::
+
+If the build info from the `.contract` file matches the environment and a
+docker `image` is present in metadata, `cargo contract` will build the
+ project inside the specified `image` docker container. 
+Otherwise, a local build is carried out.
+
+Upon completion, the built contract bundle is compared to the reference one
+and the result is returned.
+
+## Advanced usage
+
+If you would like to carry out other operations inside a deterministic environment
+you can use our docker image. It is availble on [Docker Hub](https://hub.docker.com/repository/docker/paritytech/contracts-verifiable/general).
+The entry point is set to `cargo contract` allowing you to specify other commands to be
+executed.
+
+:::tip
+If you are building a multi-contract project, 
+make sure you are executing the build in the parent directory in order to mount the directory 
+of all contracts to be visible. Specify a relative manifest path to the root contract: 
+
+`cargo contract build --verifiable --release --manifest-path ink-project-a/Cargo.toml`
+:::
+
+You can find a Dockefile and further documentation on image usage 
+in [the `cargo-contract` repository](https://github.com/paritytech/cargo-contract/tree/master/build-image)

docs/basics/verification.md → docs/basics/verification/sirato.md

@@ -1,40 +1,12 @@
 ---
-title: Contract Verification
-slug: /basics/contract-verification
+title: Sirato 
+slug: /basics/verification/sirato
 hide_title: true
 ---
 
 <img src="/img/title/magnifying-glass.svg" className="titlePic" />
 
-# Contract Verification
-
-Contract verification is the process of matching a deployed ink! contract 
-with the source code and metadata generated when it was built. 
-
-The verification process for Wasm-based smart contract languages is more
-complex than EVM-based languages such as Solidity due to the Rust 
-compiler not providing deterministic builds of contracts. 
-
-In order to verify an ink! or Wasm smart contract the verification
-process must recompile the contract in an identical host environment to
-which it was originally built. The simplest way to do this is using a Docker
-container.
-
-As this will not be possible with existing smart contracts, a fallback 
-mechanism has been created where a contract deployer can provide a 
-signed metadata file to associate with the contract. This approach is also
-outlined below.
-
-:::note
-At the current time, the `cargo-contract` CLI tool does not provide a Docker
-image for ink! creating verifiable builds. The following 
-[issue](https://github.com/paritytech/cargo-contract/issues/1065)
-has been created with details of this.
-
-As an interim solution, Web3 Labs are publishing a
-[container image](https://github.com/web3labs/ink-verifier-image) for ink!
-smart contract source code verification.
-:::
+# Sirato Verification Service
 
 Web3 Labs have made available a public version of their
 [verification service](https://github.com/web3labs/ink-verifier-server) 

sidebars.js

@@ -34,7 +34,15 @@ module.exports = {
       "basics/metadata",
       "basics/testing",
       "basics/debugging",
-      "basics/verification",
+      {
+        type: "category",
+        label: "Verification",
+        items: [
+          "basics/verification/contract-verification",
+          "basics/verification/sirato"
+        ]
+      }
+      // "basics/verification",
     ],
     "Macros & Attributes": [
       "macros-attributes/overview",

workspace.txt

@@ -24,6 +24,7 @@ debuggability
 devnet
 dispatchable
 dispatchables
+dockerfile
 dylint
 edsl
 enjin