From a21db0aa3d69a491c098c42f5541c7fdacf44b24 Mon Sep 17 00:00:00 2001 From: Dan Forbes Date: Sat, 12 Nov 2022 04:57:07 -0800 Subject: [PATCH 1/2] Prettier --- README.md | 62 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 44 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 8c2d040ad1..403971051d 100644 --- a/README.md +++ b/README.md @@ -33,12 +33,18 @@ ## A Go Implementation of the Polkadot Host -> **Warning** -> 2022-11-01: Gossamer is pre-production software +> **Warning** 2022-11-01: Gossamer is pre-production software -Gossamer is an implementation of the [Polkadot Host](https://wiki.polkadot.network/docs/learn-polkadot-host): an execution environment for the Polkadot runtime, which is materialized as a Web Assembly (Wasm) blob. In addition to running an embedded Wasm executor, a Polkadot Host must orchestrate a number of interrelated services, such as [networking](dot/network/README.md), block production, block finalization, a JSON-RPC server, [and more](cmd/gossamer/README.md). +Gossamer is an implementation of the +[Polkadot Host](https://wiki.polkadot.network/docs/learn-polkadot-host): an +execution environment for the Polkadot runtime, which is materialized as a Web +Assembly (Wasm) blob. In addition to running an embedded Wasm executor, a +Polkadot Host must orchestrate a number of interrelated services, such as +[networking](dot/network/README.md), block production, block finalization, a +JSON-RPC server, [and more](cmd/gossamer/README.md). -For more information about Gossamer, check out the [Gossamer Docs](https://ChainSafe.github.io/gossamer). +For more information about Gossamer, check out the +[Gossamer Docs](https://ChainSafe.github.io/gossamer). ## Get Started @@ -94,11 +100,15 @@ To start the development node: ./bin/gossamer --chain dev ``` -The development node is configured to produce a block every slot and to finalise a block every round (as there is only one authority, `alice`.) +The development node is configured to produce a block every slot and to finalise +a block every round (as there is only one authority, `alice`.) ### Run Gossamer Node -The gossamer node runs by default as an authority with 9 authorites set at genesis. The built-in keys, corresponding to the authorities, that are available for the node are `alice`, `bob`, `charlie`, `dave`, `eve`, `ferdie`, `george`, and `ian`. +The gossamer node runs by default as an authority with 9 authorites set at +genesis. The built-in keys, corresponding to the authorities, that are available +for the node are `alice`, `bob`, `charlie`, `dave`, `eve`, `ferdie`, `george`, +and `ian`. To initialise a gossamer node: @@ -112,11 +122,17 @@ To start the gossamer node: ./bin/gossamer --chain gssmr --key alice ``` -Note: If you only run one gossamer node, the node will not build blocks every slot or finalize blocks; it will appear that the node is doing nothing, but it is actually waiting for a slot to build a block. This is because there are 9 authorities set, so at least 6 of the authorities should be run for a functional network. If you wish to reduce the number of authorities, you can modify the genesis file in `chain/gssmr/genesis-spec.json`. +Note: If you only run one gossamer node, the node will not build blocks every +slot or finalize blocks; it will appear that the node is doing nothing, but it +is actually waiting for a slot to build a block. This is because there are 9 +authorities set, so at least 6 of the authorities should be run for a functional +network. If you wish to reduce the number of authorities, you can modify the +genesis file in `chain/gssmr/genesis-spec.json`. ### Run Kusama Node -Kusama is currently supported as a **full node**, ie. it can sync the chain but not act as an authority. +Kusama is currently supported as a **full node**, ie. it can sync the chain but +not act as an authority. To initialise a kusama node: @@ -130,7 +146,9 @@ To start the kusama node: ./bin/gossamer --chain kusama ``` -The node may not appear to do anything for the first minute or so (it's bootstrapping to the network.) If you wish to see what is it doing in this time, you can turn on debug logs in `chain/gssmr/config.toml`: +The node may not appear to do anything for the first minute or so (it's +bootstrapping to the network.) If you wish to see what is it doing in this time, +you can turn on debug logs in `chain/gssmr/config.toml`: ``` [log] @@ -141,7 +159,8 @@ After it's finished bootstrapping, the node should begin to sync. ### Run Polkadot Node -Polkadot is currently supported as a **full node**, ie. it can sync the chain but not act as an authority. +Polkadot is currently supported as a **full node**, ie. it can sync the chain +but not act as an authority. To initialise a polkadot node: @@ -157,25 +176,32 @@ To start the polkadot node: ## Contribute -- Check out [Contributing Guidelines](.github/CONTRIBUTING.md) and our [code style](.github/CODE_STYLE.md) document +- Check out [Contributing Guidelines](.github/CONTRIBUTING.md) and our + [code style](.github/CODE_STYLE.md) document - Have questions? Say hi on [Discord](https://discord.gg/Xdc5xjE)! ## Donate -Our work on Gossamer is funded by the community. If you'd like to support us with a donation: -- DOT: [`14gaKBxYkbBh2SKGtRDdhuhtyGAs5XLh55bE5x4cDi5CmL75`](https://polkadot.subscan.io/account/14gaKBxYkbBh2SKGtRDdhuhtyGAs5XLh55bE5x4cDi5CmL75) -- KSM: [`FAjhFSFoM6X8CxeSp6JE2fPECauCA5NxyB1rAGNSkrVaMtf`](https://kusama.subscan.io/account/FAjhFSFoM6X8CxeSp6JE2fPECauCA5NxyB1rAGNSkrVaMtf) +Our work on Gossamer is funded by the community. If you'd like to support us +with a donation: + +- DOT: + [`14gaKBxYkbBh2SKGtRDdhuhtyGAs5XLh55bE5x4cDi5CmL75`](https://polkadot.subscan.io/account/14gaKBxYkbBh2SKGtRDdhuhtyGAs5XLh55bE5x4cDi5CmL75) +- KSM: + [`FAjhFSFoM6X8CxeSp6JE2fPECauCA5NxyB1rAGNSkrVaMtf`](https://kusama.subscan.io/account/FAjhFSFoM6X8CxeSp6JE2fPECauCA5NxyB1rAGNSkrVaMtf) - ETH/DAI: `0x764001D60E69f0C3D0b41B0588866cFaE796972c` ## ChainSafe Security Policy ### Reporting a Security Bug -We take all security issues seriously, if you believe you have found a security issue within a ChainSafe -project please notify us immediately. If an issue is confirmed, we will take all necessary precautions -to ensure a statement and patch release is made in a timely manner. +We take all security issues seriously, if you believe you have found a security +issue within a ChainSafe project please notify us immediately. If an issue is +confirmed, we will take all necessary precautions to ensure a statement and +patch release is made in a timely manner. -Please email us a description of the flaw and any related information (e.g. reproduction steps, version) to +Please email us a description of the flaw and any related information (e.g. +reproduction steps, version) to [security at chainsafe dot io](mailto:security@chainsafe.io). ## License From 6b3d6667b06651c970ec3795cef8d4cc896deb07 Mon Sep 17 00:00:00 2001 From: Dan Forbes Date: Thu, 17 Nov 2022 14:42:28 -0800 Subject: [PATCH 2/2] README Changes for 22Q4 Release --- README.md | 183 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 95 insertions(+), 88 deletions(-) diff --git a/README.md b/README.md index 403971051d..51b5227fa9 100644 --- a/README.md +++ b/README.md @@ -31,154 +31,161 @@
-## A Go Implementation of the Polkadot Host +> **Warning** +> +> The Gossamer Polkadot Host is pre-production software [2022-12-01] -> **Warning** 2022-11-01: Gossamer is pre-production software - -Gossamer is an implementation of the +Gossamer is a [Golang](https://go.dev/) implementation of the [Polkadot Host](https://wiki.polkadot.network/docs/learn-polkadot-host): an execution environment for the Polkadot runtime, which is materialized as a Web Assembly (Wasm) blob. In addition to running an embedded Wasm executor, a Polkadot Host must orchestrate a number of interrelated services, such as [networking](dot/network/README.md), block production, block finalization, a -JSON-RPC server, [and more](cmd/gossamer/README.md). +JSON-RPC server, [and more](cmd/gossamer/README.md#client-components). -For more information about Gossamer, check out the -[Gossamer Docs](https://ChainSafe.github.io/gossamer). +## Getting Started -## Get Started +To get started with Gossamer, follow the steps below to build the source code +and start a development network. ### Prerequisites -Install Go version [`>=1.18`](https://go.dev/dl/#go1.18) +[Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) is required +to acquire the Gossamer source code, and +[Make](https://tilburgsciencehub.com/building-blocks/configure-your-computer/automation-and-workflows/make/) +is used to build it. Building Gossamer requires version 1.18 of +[Golang](https://go.dev/dl/). + +> **Warning** +> +> Gossamer will NOT work with version 1.19 of Golang. ### Installation -get the [ChainSafe/gossamer](https://github.com/ChainSafe/gossamer) repository: +Clone the [Gossamer](https://github.com/ChainSafe/gossamer) repository and +checkout the `development` branch: -``` +```sh git clone git@github.com:ChainSafe/gossamer cd gossamer +git checkout development ``` -build gossamer command: +Build Gossamer: -``` +```sh make gossamer ``` -### Troubleshooting for Apple Silicon users - -If you are facing the following problem with the `wasmer`: +Or build Gossamer _and_ move the resulting executable to `$GOPATH/bin`: +```sh +make install ``` + +To install Gossamer + +#### Troubleshooting for Apple Silicon users + +Apple Silicon users may encounter these errors: + +```sh undefined: cWasmerImportObjectT undefined: cWasmerImportFuncT undefined: cWasmerValueTag ``` -Make sure you have the following Golang enviroment variables: +If so, set the following +[Golang environment variables](https://pkg.go.dev/cmd/go#hdr-Environment_variables): -- GOARCH="amd64" -- CGO_ENABLED="1" +```sh +GOARCH="amd64" +``` -> use _go env_ to see all the Golang enviroment variables +## Use Gossamer -> use _go env -w **ENV_NAME**=**ENV_VALUE**_ to set the new value +A comprehensive guide to +[Gossamer's end-user capabilities](cmd/gossamer/README.md) is located in the +`cmd/gossamer` directory. What follows is a guide to Gossamer's capabilities as +a Polkadot Host. -### Run Development Node +### Chain Specifications -To initialise a development node: +A chain specification is a JSON document that defines the +[genesis](https://wiki.polkadot.network/docs/glossary#genesis) block of a +blockchain network, as well as network parameters and metadata (e.g. network +name, bootnodes, +[telemetry endpoints](https://wiki.polkadot.network/docs/build-node-management#monitoring-and-telemetry), +etc). It is necessary to provide Gossamer with a chain specification in order to +use it as a Polkadot Host. The Gossamer repository includes a number of chain +specifications, some of which will be used in this guide. -``` -./bin/gossamer --chain dev init -``` +### Configuration Files -To start the development node: +Gossamer exposes a number of configuration parameters, such as the location of a +chain specification file. Although it's possible to use command-line parameters, +this guide will focus on the usage of Gossamer TOML configuration files, which +define a set of configuration values in a declarative, portable, reusable +format. The chain specifications that are used in this guide are each +accompanied by one or more configuration files. -``` -./bin/gossamer --chain dev -``` +### Single-Node Development Network -The development node is configured to produce a block every slot and to finalise -a block every round (as there is only one authority, `alice`.) +The name of the Polkadot test network is "Westend", and the Gossamer repository +includes a chain specification and configuration file for a single-node, local +Westend test network. -### Run Gossamer Node - -The gossamer node runs by default as an authority with 9 authorites set at -genesis. The built-in keys, corresponding to the authorities, that are available -for the node are `alice`, `bob`, `charlie`, `dave`, `eve`, `ferdie`, `george`, -and `ian`. - -To initialise a gossamer node: +First, initialize the directory that will be used by the Gossamer node to manage +its state: -``` -./bin/gossamer --chain gssmr init +```sh +./bin/gossamer init --force --config ./chain/westend-dev/config.toml ``` -To start the gossamer node: +Now, start Gossamer as a host for the local Westend development chain: -``` -./bin/gossamer --chain gssmr --key alice +```sh +./bin/gossamer --config ./chain/westend-dev/config.toml ``` -Note: If you only run one gossamer node, the node will not build blocks every -slot or finalize blocks; it will appear that the node is doing nothing, but it -is actually waiting for a slot to build a block. This is because there are 9 -authorities set, so at least 6 of the authorities should be run for a functional -network. If you wish to reduce the number of authorities, you can modify the -genesis file in `chain/gssmr/genesis-spec.json`. +### Multi-Node Development Network -### Run Kusama Node +The multi-node development network includes three participants: the Alice, Bob, +and Charlie test accounts. In three separate terminals, initialize the data +directories for the three Gossamer instances: -Kusama is currently supported as a **full node**, ie. it can sync the chain but -not act as an authority. - -To initialise a kusama node: - -``` -./bin/gossamer --chain kusama init +```sh +./bin/gossamer init --force --config ./chain/westend-local/config-alice.toml ``` -To start the kusama node: - -``` -./bin/gossamer --chain kusama +```sh +./bin/gossamer init --force --config ./chain/westend-local/config-bob.toml ``` -The node may not appear to do anything for the first minute or so (it's -bootstrapping to the network.) If you wish to see what is it doing in this time, -you can turn on debug logs in `chain/gssmr/config.toml`: - -``` -[log] -network = "debug" +```sh +./bin/gossamer init --force --config ./chain/westend-local/config-charlie.toml ``` -After it's finished bootstrapping, the node should begin to sync. - -### Run Polkadot Node - -Polkadot is currently supported as a **full node**, ie. it can sync the chain -but not act as an authority. +Then start the three hosts: -To initialise a polkadot node: - -``` -./bin/gossamer --chain polkadot init +```sh +./bin/gossamer --config ./chain/westend-local/config-alice.toml ``` -To start the polkadot node: - +```sh +./bin/gossamer --config ./chain/westend-local/config-bob.toml ``` -./bin/gossamer --chain polkadot + +```sh +./bin/gossamer --config ./chain/westend-local/config-charlie.toml ``` ## Contribute -- Check out [Contributing Guidelines](.github/CONTRIBUTING.md) and our - [code style](.github/CODE_STYLE.md) document -- Have questions? Say hi on [Discord](https://discord.gg/Xdc5xjE)! +- Check out the [Contributing Guidelines](.github/CONTRIBUTING.md) and our + [style guide](.github/CODE_STYLE.md). +- Have questions or just want to say hi? Join us on + [Discord](https://discord.gg/Xdc5xjE)! ## Donate @@ -193,13 +200,13 @@ with a donation: ## ChainSafe Security Policy -### Reporting a Security Bug - We take all security issues seriously, if you believe you have found a security issue within a ChainSafe project please notify us immediately. If an issue is confirmed, we will take all necessary precautions to ensure a statement and patch release is made in a timely manner. +### Reporting a Security Bug + Please email us a description of the flaw and any related information (e.g. reproduction steps, version) to [security at chainsafe dot io](mailto:security@chainsafe.io).