[Substrate.io] Deterministic Runtime #26
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| However, you don't need to know anything about using Docker to build a Substrate-based chain using `srtool` because you can use the `srtool-cli` command-line interface to work with Docker images. | ||
|
|
||
| The `srtool-cli` package is a command-line utility written in Rust that installs an executable program called `srtool` on your computer. | ||
| This program simplifies your interactions with the srtool Docker container. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'srtool'?
| However, you don't need to know anything about using Docker to build a Substrate-based chain using `srtool` because you can use the `srtool-cli` command-line interface to work with Docker images. | ||
|
|
||
| The `srtool-cli` package is a command-line utility written in Rust that installs an executable program called `srtool` on your computer. | ||
| This program simplifies your interactions with the srtool Docker container. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Papermoon.CustomDictionary] Did you really mean 'srtool'?
| This program simplifies your interactions with the srtool Docker container. | ||
| Over time, the tooling around the `srtool` Docker image has expanded to include the following tools and helper programs: | ||
|
|
||
| - [srtool-cli](https://github.com/chevdor/srtool-cli){target=\_blank} provides a command-line interface to pull the srtool Docker image, get information about the image and tooling used to interact with it, and build the runtime using the `srtool` Docker container. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'srtool'?
| This program simplifies your interactions with the srtool Docker container. | ||
| Over time, the tooling around the `srtool` Docker image has expanded to include the following tools and helper programs: | ||
|
|
||
| - [srtool-cli](https://github.com/chevdor/srtool-cli){target=\_blank} provides a command-line interface to pull the srtool Docker image, get information about the image and tooling used to interact with it, and build the runtime using the `srtool` Docker container. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Papermoon.CustomDictionary] Did you really mean 'srtool'?
|
|
||
| - [srtool-cli](https://github.com/chevdor/srtool-cli){target=\_blank} provides a command-line interface to pull the srtool Docker image, get information about the image and tooling used to interact with it, and build the runtime using the `srtool` Docker container. | ||
|
|
||
| - [subwasm](https://github.com/chevdor/subwasm){target=\_blank} provides command-line options for working with the metadata and WebAssembly runtime built using srtool. The `subwasm` program is also used internally to perform tasks in the `srtool` image. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Papermoon.CustomDictionary] Did you really mean 'srtool'?
|
|
||
| - [srtool-cli](https://github.com/chevdor/srtool-cli){target=\_blank} provides a command-line interface to pull the srtool Docker image, get information about the image and tooling used to interact with it, and build the runtime using the `srtool` Docker container. | ||
|
|
||
| - [subwasm](https://github.com/chevdor/subwasm){target=\_blank} provides command-line options for working with the metadata and WebAssembly runtime built using srtool. The `subwasm` program is also used internally to perform tasks in the `srtool` image. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'srtool'?
| - The name you specify for the `--package` should be the name defined in the `Cargo.toml` file for the runtime. | ||
|
|
||
| - The path you specify for the `--runtime-dir` should be the path to the `Cargo.toml` file for the runtime. | ||
| If the `Cargo.toml` file for the runtime is located in a `runtime` subdirectory—for example, runtime/kusama—you can omit the `--runtime-dir` command-line option. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Terms] Use 'Kusama' instead of 'kusama'.
|
|
||
| This is problematic in a blockchain network where all nodes must use exactly the same raw chain specification file. | ||
|
|
||
| Working with builds that aren't guaranteed to be deterministically reproducible can cause other problems, too. For example, for automating the build processes for a blockchain, it is ideal that the same code always produces the same result (in terms of bytecode). Without a deterministic build, compiling the WebAssembly runtime with every push would produce inconsistent and unpredictable results, making it difficult to integrate with any automation and likely to continuously break a CI/CD pipeline. Deterministic builds—code that always compiles to exactly the same bytecode—also ensure that the WebAssembly runtime can be inspected, audited, and independently verified. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Google.Spacing] 'o. F' should have one space.
|
|
||
| Over time, the tooling around the `srtool` Docker image has expanded to include the following tools and helper programs: | ||
|
|
||
| - [`srtool-cli`](https://github.com/chevdor/srtool-cli){target=\_blank} provides a command-line interface to pull the srtool Docker image, get information about the image and tooling used to interact with it, and build the runtime using the `srtool` Docker container |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'srtool'?
|
|
||
| Over time, the tooling around the `srtool` Docker image has expanded to include the following tools and helper programs: | ||
|
|
||
| - [`srtool-cli`](https://github.com/chevdor/srtool-cli){target=\_blank} provides a command-line interface to pull the srtool Docker image, get information about the image and tooling used to interact with it, and build the runtime using the `srtool` Docker container |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Papermoon.CustomDictionary] Did you really mean 'srtool'?
| Over time, the tooling around the `srtool` Docker image has expanded to include the following tools and helper programs: | ||
|
|
||
| - [`srtool-cli`](https://github.com/chevdor/srtool-cli){target=\_blank} provides a command-line interface to pull the srtool Docker image, get information about the image and tooling used to interact with it, and build the runtime using the `srtool` Docker container | ||
| - [`subwasm`](https://github.com/chevdor/subwasm){target=\_blank} provides command-line options for working with the metadata and WebAssembly runtime built using srtool. The `subwasm` program is also used internally to perform tasks in the `srtool` image |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Papermoon.CustomDictionary] Did you really mean 'srtool'?
| Over time, the tooling around the `srtool` Docker image has expanded to include the following tools and helper programs: | ||
|
|
||
| - [`srtool-cli`](https://github.com/chevdor/srtool-cli){target=\_blank} provides a command-line interface to pull the srtool Docker image, get information about the image and tooling used to interact with it, and build the runtime using the `srtool` Docker container | ||
| - [`subwasm`](https://github.com/chevdor/subwasm){target=\_blank} provides command-line options for working with the metadata and WebAssembly runtime built using srtool. The `subwasm` program is also used internally to perform tasks in the `srtool` image |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'srtool'?
|
|
||
| 1. Open a terminal shell | ||
|
|
||
| 2. Verify that that Docker is installed by running the following command: |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Repetition] 'that' is repeated!
|
|
||
| 5. Type a name for the action file, and commit | ||
|
|
||
| If utilizing [`srtool-cli`](/reference/command-line-tools/srtool/#srtool-cli){target=\_blank} or [`srtool-app`](https://gitlab.com/chevdor/srtool-app){target=\_blank} is not an option, the `paritytech/srtool` container image can be used directly via Docker Hub. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Papermoon.NotContractions] Use 'isn't' instead of 'is not'.
|
|
||
| ### Naming Convention for Images | ||
|
|
||
| Keep in mind that there is no `latest` tag for the `srtool` image. Ensure that the image selected is compatible with the version of the Rust compiler that is locally available. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Google.Spacing] 'e. E' should have one space.
0xLucca
reviewed
Sep 23, 2024
| description: Explains how to use the Substrate runtime toolbox and Docker to build deterministic WebAssembly binaries for Polkadot SDK-based chains. | ||
| --- | ||
|
|
||
| By default, the Rust compiler produces optimized WebAssembly binaries. These binaries are suitable for working in an isolated environment, such as local development. However, the WebAssembly binaries that the compiler builds by default aren't guaranteed to be deterministically reproducible. Each time the compiler generates the WebAssembly runtime, it might produce slightly different WebAssembly byte code. |
There was a problem hiding this comment.
Suggested change
| By default, the Rust compiler produces optimized WebAssembly binaries. These binaries are suitable for working in an isolated environment, such as local development. However, the WebAssembly binaries that the compiler builds by default aren't guaranteed to be deterministically reproducible. Each time the compiler generates the WebAssembly runtime, it might produce slightly different WebAssembly byte code. | |
| By default, the Rust compiler produces optimized Wasm binaries. These binaries are suitable for working in an isolated environment, such as local development. However, the WebAssembly binaries that the compiler builds by default aren't guaranteed to be deterministically reproducible. Each time the compiler generates the WebAssembly runtime, it might produce slightly different WebAssembly byte code. |
I think we decided to stick to the Wasm term. Fix other occurrences
0xLucca
reviewed
Sep 23, 2024
Comment on lines
+5
to
+6
|
|
||
| By default, the Rust compiler produces optimized WebAssembly binaries. These binaries are suitable for working in an isolated environment, such as local development. However, the WebAssembly binaries that the compiler builds by default aren't guaranteed to be deterministically reproducible. Each time the compiler generates the WebAssembly runtime, it might produce slightly different WebAssembly byte code. |
There was a problem hiding this comment.
Suggested change
| By default, the Rust compiler produces optimized WebAssembly binaries. These binaries are suitable for working in an isolated environment, such as local development. However, the WebAssembly binaries that the compiler builds by default aren't guaranteed to be deterministically reproducible. Each time the compiler generates the WebAssembly runtime, it might produce slightly different WebAssembly byte code. | |
| ## Introduction | |
| By default, the Rust compiler produces optimized WebAssembly binaries. These binaries are suitable for working in an isolated environment, such as local development. However, the WebAssembly binaries that the compiler builds by default aren't guaranteed to be deterministically reproducible. Each time the compiler generates the WebAssembly runtime, it might produce slightly different WebAssembly byte code. |
0xLucca
reviewed
Sep 23, 2024
| This is problematic in a blockchain network where all nodes must use exactly the same raw chain specification file. | ||
|
|
||
| Working with builds that aren't guaranteed to be deterministically reproducible can cause other problems, too. For example, for automating the build processes for a blockchain, it is ideal that the same code always produces the same result (in terms of bytecode). Without a deterministic build, compiling the WebAssembly runtime with every push would produce inconsistent and unpredictable results, making it difficult to integrate with any automation and likely to continuously break a CI/CD pipeline. Deterministic builds—code that always compiles to exactly the same bytecode—also ensure that the WebAssembly runtime can be inspected, audited, and independently verified. | ||
|
|
There was a problem hiding this comment.
You could also add a ##Prerequisites section after the introduction
0xLucca
reviewed
Sep 23, 2024
| If Docker is installed, the command displays version information: | ||
|
|
||
| ```text | ||
| Docker version 20.10.17, build 100c701 |
There was a problem hiding this comment.
For terminal output you should use the Termynal plugin
Suggested change
| Docker version 20.10.17, build 100c701 | |
| <div id='termynal' data-termynal> | |
| <span data-ty="input"><span class="file-path"></span>docker --version</span> | |
| <span data-ty>Docker version 20.10.17, build 100c701</span> | |
| </div> |
0xLucca
reviewed
Sep 23, 2024
|
|
||
| 2. Verify that that Docker is installed by running the following command: | ||
|
|
||
| ```bash |
There was a problem hiding this comment.
Indented text under a list item should have a tab or four spaces. If not, it will break formatting. You have three spaces in most of these kind of sections.
0xLucca
reviewed
Sep 23, 2024
| 4. View usage information for the `srtool` command-line interface by running the following command: | ||
|
|
||
| ```bash | ||
| srtool help |
There was a problem hiding this comment.
You could show the output of the command using the termynal plugin
0xLucca
reviewed
Sep 23, 2024
| - The path specified for the `--runtime-dir` should be the path to the `Cargo.toml` file for the runtime | ||
| - If the `Cargo.toml` file for the runtime is located in a `runtime` subdirectory, for example, `runtime/kusama`, the `--runtime-dir` parameter can be omitted | ||
|
|
||
| ## Add Workflow Actions |
There was a problem hiding this comment.
I think this title is not self-explanatory. Something like Use Srtool in Github Actions or similar may fit better
0xLucca
reviewed
Sep 23, 2024
|
|
||
| To add a GitHub workflow for building the runtime: | ||
|
|
||
| 1. Create a `.github/workflows` directory in the chain's directory |
There was a problem hiding this comment.
It will be better to see the content of the files being added here. Also, I think using the steps of the GitHub UI to do this may not be the best way of explaining it. We can just say create the directory, and then add the file and show the basic.yml content in there keeping the link to the srtools-actions repo.
0xLucca
reviewed
Sep 23, 2024
|
|
||
| 5. Type a name for the action file, and commit | ||
|
|
||
| If utilizing [`srtool-cli`](/reference/command-line-tools/srtool/#srtool-cli){target=\_blank} or [`srtool-app`](https://gitlab.com/chevdor/srtool-app){target=\_blank} is not an option, the `paritytech/srtool` container image can be used directly via Docker Hub. |
There was a problem hiding this comment.
This should be a different section
0xLucca
reviewed
Sep 23, 2024
|
|
||
| The command downloads and unpacks the image. | ||
|
|
||
| ### Naming Convention for Images |
There was a problem hiding this comment.
This content should not be in a subsection under the Github Action section. It is a thing by its own
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The "Deterministic Runtime" page was migrated from Substrate.io: https://docs.substrate.io/build/build-a-deterministic-runtime/
Note that the instructions in this page work as expected.