Skip to content

README Changes for 22Q4 Release #2945

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
timwu20 merged 2 commits into from
Nov 23, 2022
Merged

README Changes for 22Q4 Release #2945

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a21db0a
Prettier
Nov 12, 2022
6b3d666
README Changes for 22Q4 Release
Nov 17, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
189 changes: 111 additions & 78 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,151 +31,184 @@
</div>
<br />

## A Go Implementation of the Polkadot Host

> **Warning**
> 2022-11-01: Gossamer is pre-production software
>
> The Gossamer Polkadot Host is pre-production software [2022-12-01]

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 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#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
Comment thread
danforbes marked this conversation as resolved.
```

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
```

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`.)
### Single-Node Development Network

### Run Gossamer Node
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.

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`.
First, initialize the directory that will be used by the Gossamer node to manage
its state:

To initialise a gossamer node:

```
./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:

```sh
./bin/gossamer --config ./chain/westend-dev/config.toml
```
./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`.

### Run Kusama Node

Kusama is currently supported as a **full node**, ie. it can sync the chain but not act as an authority.
### Multi-Node Development Network

To initialise a 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:

```sh
./bin/gossamer init --force --config ./chain/westend-local/config-alice.toml
```
./bin/gossamer --chain kusama init
```

To start the kusama node:

```sh
./bin/gossamer init --force --config ./chain/westend-local/config-bob.toml
```
./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`:

```sh
./bin/gossamer init --force --config ./chain/westend-local/config-charlie.toml
```
[log]
network = "debug"
```

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.

To initialise a polkadot node:
Then start the three hosts:

```sh
./bin/gossamer --config ./chain/westend-local/config-alice.toml
```
./bin/gossamer --chain polkadot init
```

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

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.
### Reporting a Security Bug

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).
Comment thread
danforbes marked this conversation as resolved.

## License
Expand Down