diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 86de490122..e34ef3b777 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -44,7 +44,7 @@ $ git remote -v (you should see myrepo and gossamer in the list of remotes) To start, check out our open issues. We recommend starting with an [issue labeled `Good First Issue`](https://github.com/ChainSafe/gossamer/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22). Leave a comment to let us know that you would like to work on it. -Another option is to improve gossamer where you see fit based on your evaluation of our code. In order to best faciliate collabration, please create an issue before you start working on it. +Another option is to improve gossamer where you see fit based on your evaluation of our code. In order to best faciliate collaboration, please create an issue before you start working on it. **6. Make improvements to the code.** diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 45bc4d939b..7a8364125c 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,56 +1,21 @@ -name: docs - +name: Publish docs via GitHub Pages on: push: branches: - development -env: - RUBY_VERSION: 2.7 - BUNDLE_GEMFILE: docs/Gemfile - jobs: - deploy_docs: - runs-on: 'ubuntu-latest' + build: + name: Deploy docs + runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 - - uses: actions/setup-ruby@v1 - with: - ruby-version: ${{ env.RUBY_VERSION }} - - name: Setup cache for Bundler - id: cache - uses: actions/cache@v2 - with: - path: vendor/bundle - key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile.lock') }} - restore-keys: | - ${{ runner.os }}-gems- - - name: Set up dependencies - run: | - bundle install --path=vendor/bundle --jobs 4 --retry 3 - bundle clean - - name: Clone target branch - run: | - REMOTE_BRANCH="${REMOTE_BRANCH:-gh-pages}" - REMOTE_REPO="https://${GITHUB_ACTOR}:${{ secrets.GITHUB_TOKEN }}@github.com/${GITHUB_REPOSITORY}.git" - echo "Publishing to ${GITHUB_REPOSITORY} on branch ${REMOTE_BRANCH}" - rm -rf docs/_site/ - git clone --depth=1 --branch="${REMOTE_BRANCH}" --single-branch --no-checkout \ - "${REMOTE_REPO}" docs/_site/ - - name: Build site - run: bundle exec jekyll build --source docs --destination docs/_site --verbose --trace + - name: Checkout main + uses: actions/checkout@v2 + + - name: Deploy docs + uses: mhausenblas/mkdocs-deploy-gh-pages@master env: - # For jekyll-github-metadata - JEKYLL_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - - name: Deploy to GitHub Pages - run: | - SOURCE_COMMIT="$(git log -1 --pretty="%an: %B" "$GITHUB_SHA")" - pushd docs/_site &>/dev/null - : > .nojekyll - git add --all - git -c user.name="${GITHUB_ACTOR}" -c user.email="${GITHUB_ACTOR}@users.noreply.github.com" \ - commit --quiet \ - --message "Deploy docs from ${GITHUB_SHA}" \ - --message "$SOURCE_COMMIT" - git push - popd &>/dev/null \ No newline at end of file + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + CUSTOM_DOMAIN: gossamer.chainsafe.io + CONFIG_FILE: docs/mkdocs.yml + EXTRA_PACKAGES: build-base \ No newline at end of file diff --git a/Makefile b/Makefile index bd17f547bb..f929b72a43 100644 --- a/Makefile +++ b/Makefile @@ -126,4 +126,11 @@ gossamer: clean ## install: install the gossamer binary in $GOPATH/bin install: - GOBIN=$(GOPATH)/bin go run scripts/ci.go install \ No newline at end of file + GOBIN=$(GOPATH)/bin go run scripts/ci.go install + +build-mkdocs: + docker run --rm -it -v ${PWD}:/docs/docs squidfunk/mkdocs-material build + +mkdocs: + docker run --rm -it -p 8000:8000 -v ${PWD}:/docs/docs squidfunk/mkdocs-material + diff --git a/cmd/gossamer/flags.go b/cmd/gossamer/flags.go index e115115286..0a877af8a5 100644 --- a/cmd/gossamer/flags.go +++ b/cmd/gossamer/flags.go @@ -230,7 +230,7 @@ var ( // ImportRawFlag imports a raw private key ImportRawFlag = cli.StringFlag{ Name: "import-raw", - Usage: "Import encrypted keystore file generated with gossamer", + Usage: "Import a raw private key", } // ListFlag List node keys ListFlag = cli.BoolFlag{ diff --git a/docs/Gemfile b/docs/Gemfile deleted file mode 100644 index 85a5863381..0000000000 --- a/docs/Gemfile +++ /dev/null @@ -1,19 +0,0 @@ -source "https://rubygems.org" - -# Hello! This is where you manage which Jekyll version is used to run. -# When you want to use a different version, change it below, save the -# file and run `bundle install`. Run Jekyll with `bundle exec`, like so: -# -# bundle exec jekyll serve -# - -# This will help ensure the proper Jekyll version is running. -# gem "jekyll", "~> 4.0.0" -gem "jekyll-relative-links" - -# This is the default theme for new Jekyll sites. You may change this to anything you like. -gem "minima", git: "https://github.com/jekyll/minima" - -# If you want to use GitHub Pages, remove the "gem "jekyll"" above and -# uncomment the line below. To upgrade, run `bundle update github-pages`. -gem "github-pages", group: :jekyll_plugins diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock deleted file mode 100644 index 6c64a71c80..0000000000 --- a/docs/Gemfile.lock +++ /dev/null @@ -1,259 +0,0 @@ -GIT - remote: https://github.com/jekyll/minima - revision: 49f6dce0727a2441f0b0c265b41b5efc7b042eb6 - specs: - minima (2.5.0) - jekyll (>= 3.5, < 5.0) - jekyll-feed (~> 0.9) - jekyll-seo-tag (~> 2.1) - -GEM - remote: https://rubygems.org/ - specs: - activesupport (4.2.11.1) - i18n (~> 0.7) - minitest (~> 5.1) - thread_safe (~> 0.3, >= 0.3.4) - tzinfo (~> 1.1) - addressable (2.7.0) - public_suffix (>= 2.0.2, < 5.0) - coffee-script (2.4.1) - coffee-script-source - execjs - coffee-script-source (1.11.1) - colorator (1.1.0) - commonmarker (0.17.13) - ruby-enum (~> 0.5) - concurrent-ruby (1.1.6) - dnsruby (1.61.3) - addressable (~> 2.5) - em-websocket (0.5.1) - eventmachine (>= 0.12.9) - http_parser.rb (~> 0.6.0) - ethon (0.12.0) - ffi (>= 1.3.0) - eventmachine (1.2.7) - execjs (2.7.0) - faraday (1.0.1) - multipart-post (>= 1.2, < 3) - ffi (1.12.2) - forwardable-extended (2.6.0) - gemoji (3.0.1) - github-pages (202) - activesupport (= 4.2.11.1) - github-pages-health-check (= 1.16.1) - jekyll (= 3.8.5) - jekyll-avatar (= 0.6.0) - jekyll-coffeescript (= 1.1.1) - jekyll-commonmark-ghpages (= 0.1.6) - jekyll-default-layout (= 0.1.4) - jekyll-feed (= 0.11.0) - jekyll-gist (= 1.5.0) - jekyll-github-metadata (= 2.12.1) - jekyll-mentions (= 1.4.1) - jekyll-optional-front-matter (= 0.3.0) - jekyll-paginate (= 1.1.0) - jekyll-readme-index (= 0.2.0) - jekyll-redirect-from (= 0.14.0) - jekyll-relative-links (= 0.6.0) - jekyll-remote-theme (= 0.4.0) - jekyll-sass-converter (= 1.5.2) - jekyll-seo-tag (= 2.5.0) - jekyll-sitemap (= 1.2.0) - jekyll-swiss (= 0.4.0) - jekyll-theme-architect (= 0.1.1) - jekyll-theme-cayman (= 0.1.1) - jekyll-theme-dinky (= 0.1.1) - jekyll-theme-hacker (= 0.1.1) - jekyll-theme-leap-day (= 0.1.1) - jekyll-theme-merlot (= 0.1.1) - jekyll-theme-midnight (= 0.1.1) - jekyll-theme-minimal (= 0.1.1) - jekyll-theme-modernist (= 0.1.1) - jekyll-theme-primer (= 0.5.3) - jekyll-theme-slate (= 0.1.1) - jekyll-theme-tactile (= 0.1.1) - jekyll-theme-time-machine (= 0.1.1) - jekyll-titles-from-headings (= 0.5.1) - jemoji (= 0.10.2) - kramdown (= 1.17.0) - liquid (= 4.0.0) - listen (= 3.1.5) - mercenary (~> 0.3) - minima (= 2.5.0) - nokogiri (>= 1.10.4, < 2.0) - rouge (= 3.11.0) - terminal-table (~> 1.4) - github-pages-health-check (1.16.1) - addressable (~> 2.3) - dnsruby (~> 1.60) - octokit (~> 4.0) - public_suffix (~> 3.0) - typhoeus (~> 1.3) - html-pipeline (2.13.0) - activesupport (>= 2) - nokogiri (>= 1.4) - http_parser.rb (0.6.0) - i18n (0.9.5) - concurrent-ruby (~> 1.0) - jekyll (3.8.5) - addressable (~> 2.4) - colorator (~> 1.0) - em-websocket (~> 0.5) - i18n (~> 0.7) - jekyll-sass-converter (~> 1.0) - jekyll-watch (~> 2.0) - kramdown (~> 1.14) - liquid (~> 4.0) - mercenary (~> 0.3.3) - pathutil (~> 0.9) - rouge (>= 1.7, < 4) - safe_yaml (~> 1.0) - jekyll-avatar (0.6.0) - jekyll (~> 3.0) - jekyll-coffeescript (1.1.1) - coffee-script (~> 2.2) - coffee-script-source (~> 1.11.1) - jekyll-commonmark (1.3.1) - commonmarker (~> 0.14) - jekyll (>= 3.7, < 5.0) - jekyll-commonmark-ghpages (0.1.6) - commonmarker (~> 0.17.6) - jekyll-commonmark (~> 1.2) - rouge (>= 2.0, < 4.0) - jekyll-default-layout (0.1.4) - jekyll (~> 3.0) - jekyll-feed (0.11.0) - jekyll (~> 3.3) - jekyll-gist (1.5.0) - octokit (~> 4.2) - jekyll-github-metadata (2.12.1) - jekyll (~> 3.4) - octokit (~> 4.0, != 4.4.0) - jekyll-mentions (1.4.1) - html-pipeline (~> 2.3) - jekyll (~> 3.0) - jekyll-optional-front-matter (0.3.0) - jekyll (~> 3.0) - jekyll-paginate (1.1.0) - jekyll-readme-index (0.2.0) - jekyll (~> 3.0) - jekyll-redirect-from (0.14.0) - jekyll (~> 3.3) - jekyll-relative-links (0.6.0) - jekyll (~> 3.3) - jekyll-remote-theme (0.4.0) - addressable (~> 2.0) - jekyll (~> 3.5) - rubyzip (>= 1.2.1, < 3.0) - jekyll-sass-converter (1.5.2) - sass (~> 3.4) - jekyll-seo-tag (2.5.0) - jekyll (~> 3.3) - jekyll-sitemap (1.2.0) - jekyll (~> 3.3) - jekyll-swiss (0.4.0) - jekyll-theme-architect (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-cayman (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-dinky (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-hacker (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-leap-day (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-merlot (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-midnight (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-minimal (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-modernist (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-primer (0.5.3) - jekyll (~> 3.5) - jekyll-github-metadata (~> 2.9) - jekyll-seo-tag (~> 2.0) - jekyll-theme-slate (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-tactile (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-time-machine (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-titles-from-headings (0.5.1) - jekyll (~> 3.3) - jekyll-watch (2.2.1) - listen (~> 3.0) - jemoji (0.10.2) - gemoji (~> 3.0) - html-pipeline (~> 2.2) - jekyll (~> 3.0) - kramdown (1.17.0) - liquid (4.0.0) - listen (3.1.5) - rb-fsevent (~> 0.9, >= 0.9.4) - rb-inotify (~> 0.9, >= 0.9.7) - ruby_dep (~> 1.2) - mercenary (0.3.6) - mini_portile2 (2.5.0) - minitest (5.14.1) - multipart-post (2.1.1) - nokogiri (1.11.1) - mini_portile2 (~> 2.5.0) - racc (~> 1.4) - octokit (4.18.0) - faraday (>= 0.9) - sawyer (~> 0.8.0, >= 0.5.3) - pathutil (0.16.2) - forwardable-extended (~> 2.6) - public_suffix (3.1.1) - racc (1.5.2) - rb-fsevent (0.10.4) - rb-inotify (0.10.1) - ffi (~> 1.0) - rouge (3.11.0) - ruby-enum (0.8.0) - i18n - ruby_dep (1.5.0) - rubyzip (2.3.0) - safe_yaml (1.0.5) - sass (3.7.4) - sass-listen (~> 4.0.0) - sass-listen (4.0.0) - rb-fsevent (~> 0.9, >= 0.9.4) - rb-inotify (~> 0.9, >= 0.9.7) - sawyer (0.8.2) - addressable (>= 2.3.5) - faraday (> 0.8, < 2.0) - terminal-table (1.8.0) - unicode-display_width (~> 1.1, >= 1.1.1) - thread_safe (0.3.6) - typhoeus (1.4.0) - ethon (>= 0.9.0) - tzinfo (1.2.7) - thread_safe (~> 0.1) - unicode-display_width (1.7.0) - -PLATFORMS - ruby - -DEPENDENCIES - github-pages - jekyll-relative-links - minima! - -BUNDLED WITH - 2.1.4 diff --git a/docs/_config.yml b/docs/_config.yml deleted file mode 100644 index c9624dca4e..0000000000 --- a/docs/_config.yml +++ /dev/null @@ -1,105 +0,0 @@ -# Welcome to Jekyll! -# -# This config file is meant for settings that affect your whole blog, values -# which you are expected to set up once and rarely edit after that. If you find -# yourself editing this file very often, consider using Jekyll's data files -# feature for the data you need to update frequently. -# -# For technical reasons, this file is *NOT* reloaded automatically when you use -# 'bundle exec jekyll serve'. If you change this file, please restart the server process. -# -# If you need help with YAML syntax, here are some quick references for you: -# https://learn-the-web.algonquindesign.ca/topics/markdown-yaml-cheat-sheet/#yaml -# https://learnxinyminutes.com/docs/yaml/ -# -# Site settings -# These are used to personalize your new site. If you look in the HTML files, -# you will see them accessed via {{ site.title }}, {{ site.email }}, and so on. -# You can create any custom variable you would like, and they will be accessible -# in the templates via {{ site.myvariable }}. - -title: Gossamer Docs -author: - name: ChainSafe - email: info@chainsafe.io -description: > # this means to ignore newlines until "show_excerpts:" - The Official Documentation for Gossamer | A Go Implementation of the Polkadot Host -show_excerpts: false # set to true to show excerpts on the homepage - -baseurl: /gossamer/ -relative_url: /gossamer/ - -# Minima date format -# refer to https://shopify.github.io/liquid/filters/date/ if you want to customize this -minima: - date_format: "%b %-d, %Y" - skin: dark - - # generate social links in footer - social_links: - twitter: ChainSafeth - github: ChainSafe - # devto: jekyll - # dribbble: jekyll - # facebook: jekyll - # flickr: jekyll - # instagram: jekyll - # linkedin: jekyll - # pinterest: jekyll - # youtube: jekyll - # youtube_channel: UC8CXR0-3I70i1tfPg1PAE1g - # youtube_channel_name: CloudCannon - # telegram: jekyll - # googleplus: +jekyll - # microdotblog: jekyll - # keybase: jekyll - - # Mastodon instances - # mastodon: - # - username: jekyll - # instance: example.com - # - username: jekyll2 - # instance: example.com - - # GitLab instances - # gitlab: - # - username: jekyll - # instance: example.com - # - username: jekyll2 - # instance: example.com - -# If you want to link only specific pages in your menus, uncomment -# this and add the path to the pages in order as they should show up -header_pages: - - menus/Run_Nodes.md - - menus/Build_Nodes.md - - menus/Implementation.md - - menus/Resources.md -# - menus/Appendix.md - -# Build settings -theme: minima - -plugins: - - jekyll-relative-links - - jekyll-seo-tag - -# Exclude from processing. -# The following items will not be processed, by default. -# Any item listed under the `exclude:` key here will be automatically added to -# the internal "default list". -# -# Excluded items can be processed by explicitly listing the directories or -# their entries' file path in the `include:` list. -# -# exclude: -# - .sass-cache/ -# - .jekyll-cache/ -# - gemfiles/ -# - Gemfile -# - Gemfile.lock -# - node_modules/ -# - vendor/bundle/ -# - vendor/cache/ -# - vendor/gems/ -# - vendor/ruby/ diff --git a/docs/_includes/footer.html b/docs/_includes/footer.html deleted file mode 100644 index fcc7a1d14e..0000000000 --- a/docs/_includes/footer.html +++ /dev/null @@ -1,13 +0,0 @@ - diff --git a/docs/_includes/head.html b/docs/_includes/head.html deleted file mode 100644 index 383debd65d..0000000000 --- a/docs/_includes/head.html +++ /dev/null @@ -1,18 +0,0 @@ - - - - - - {%- seo -%} - - - - - {%- feed_meta -%} - - {%- if jekyll.environment == 'production' and site.google_analytics -%} - {%- include google-analytics.html -%} - {%- endif -%} - - {%- include custom-head.html -%} - diff --git a/docs/pages/404.html b/docs/docs/404.html similarity index 100% rename from docs/pages/404.html rename to docs/docs/404.html diff --git a/docs/pages/SCALE_Examples.md b/docs/docs/advanced/scale-examples.md similarity index 98% rename from docs/pages/SCALE_Examples.md rename to docs/docs/advanced/scale-examples.md index 6dbe99a5e8..8f32e5a0a2 100644 --- a/docs/pages/SCALE_Examples.md +++ b/docs/docs/advanced/scale-examples.md @@ -1,7 +1,7 @@ --- layout: default title: SCALE Examples -permalink: /scale-examples/ +permalink: /advanced/scale-examples/ --- A byte array `A` is defined as a set of bytes `(b1,...,bn)` st. `n < 2^536`. diff --git a/docs/docs/assets/Gossamer_Black_Name.svg b/docs/docs/assets/Gossamer_Black_Name.svg new file mode 100644 index 0000000000..97a95539a9 --- /dev/null +++ b/docs/docs/assets/Gossamer_Black_Name.svg @@ -0,0 +1 @@ +Gossamer - wordmark1 - B \ No newline at end of file diff --git a/docs/assets/css/style.scss b/docs/docs/assets/css/style.scss similarity index 88% rename from docs/assets/css/style.scss rename to docs/docs/assets/css/style.scss index 86c4d0f260..454b7295df 100644 --- a/docs/assets/css/style.scss +++ b/docs/docs/assets/css/style.scss @@ -1,9 +1,3 @@ ---- ---- - -@import "minima/skins/dark.scss"; -@import "minima/initialize.scss"; - body { color: #BBB !important; font-family: "ubuntu", sans-serif; diff --git a/docs/assets/favicon.ico b/docs/docs/assets/favicon.ico similarity index 100% rename from docs/assets/favicon.ico rename to docs/docs/assets/favicon.ico diff --git a/docs/docs/assets/img/block_production.png b/docs/docs/assets/img/block_production.png new file mode 100644 index 0000000000..5aecd1af46 Binary files /dev/null and b/docs/docs/assets/img/block_production.png differ diff --git a/docs/assets/img/chainsafe_gopher.png b/docs/docs/assets/img/chainsafe_gopher.png similarity index 100% rename from docs/assets/img/chainsafe_gopher.png rename to docs/docs/assets/img/chainsafe_gopher.png diff --git a/docs/assets/img/gossamer_banner.png b/docs/docs/assets/img/gossamer_banner.png similarity index 100% rename from docs/assets/img/gossamer_banner.png rename to docs/docs/assets/img/gossamer_banner.png diff --git a/docs/assets/img/gossamer_banner_white.png b/docs/docs/assets/img/gossamer_banner_white.png similarity index 100% rename from docs/assets/img/gossamer_banner_white.png rename to docs/docs/assets/img/gossamer_banner_white.png diff --git a/docs/docs/assets/tutorial/connect-1.png b/docs/docs/assets/tutorial/connect-1.png new file mode 100644 index 0000000000..49c9d87581 Binary files /dev/null and b/docs/docs/assets/tutorial/connect-1.png differ diff --git a/docs/docs/assets/tutorial/connect-2.png b/docs/docs/assets/tutorial/connect-2.png new file mode 100644 index 0000000000..21870f65ea Binary files /dev/null and b/docs/docs/assets/tutorial/connect-2.png differ diff --git a/docs/docs/assets/tutorial/connect-3.png b/docs/docs/assets/tutorial/connect-3.png new file mode 100644 index 0000000000..a0c72e46cb Binary files /dev/null and b/docs/docs/assets/tutorial/connect-3.png differ diff --git a/docs/docs/assets/tutorial/connect-4.png b/docs/docs/assets/tutorial/connect-4.png new file mode 100644 index 0000000000..d4e8a96c3d Binary files /dev/null and b/docs/docs/assets/tutorial/connect-4.png differ diff --git a/docs/docs/assets/tutorial/connect-5.png b/docs/docs/assets/tutorial/connect-5.png new file mode 100644 index 0000000000..62a4c0c3d2 Binary files /dev/null and b/docs/docs/assets/tutorial/connect-5.png differ diff --git a/docs/docs/assets/tutorial/connect-6.png b/docs/docs/assets/tutorial/connect-6.png new file mode 100644 index 0000000000..80e8f1109a Binary files /dev/null and b/docs/docs/assets/tutorial/connect-6.png differ diff --git a/docs/docs/contributing.md b/docs/docs/contributing.md new file mode 100644 index 0000000000..6e808861c6 --- /dev/null +++ b/docs/docs/contributing.md @@ -0,0 +1,132 @@ +# Contribution Guidelines + +Thank you for your interest in our implementation of the Polkadot Runtime Environment Implementation! We're excited to get to know you and work with you on gossamer. We've put together these guidelines to help you figure out how you can help us. + +At any point in this process feel free to reach out on [Discord](https://discord.gg/Xdc5xjE) with any questions or to say Hello :) + +# Getting Started + +Generally, it is important to have a basic understanding of Polkadot and the Polkadot Runtime Environment. Having a stronger understanding will allow you to make more significant contributions. We've put together a list of resources that can help you develop this fundamental knowledge. + +The Web3 Foundation has a [Polkadot Wiki](https://wiki.polkadot.network/docs/en/learn-introduction) that would help both part-time and core contributors to the project in order to get up to speed. Our [wiki](https://github.com/ChainSafe/gossamer/wiki) also has some helpful resources. + +The [Polkadot Runtime Specification](https://research.web3.foundation/en/latest/_static/pdfview/viewer.html?file=../pdf/polkadot_re_spec.pdf) serves as our primary specification, however it is currently in its draft status so things may be subject to change. + +One important thing distinction is that we are building the Polkadot Runtime Environment, not Polkadot itself. Given that, although a deep understanding of Polkadot is helpful, it's not critical to contribute to gossamer. To help understand how the Runtime Environment relates to Polkadot, check out this [talk that one of our team members gave at DotCon.](https://www.youtube.com/watch?v=nYkbYhM5Yfk) + +## Contribution Steps + +**1. Fork the gossamer repo.** + +**2. Create a local clone of gossamer.** + +``` +go get -u github.com/ChainSafe/gossamer +cd $GOPATH/src/github.com/ChainSafe/gossamer +git init +``` +You may encounter a `package github.com/ChainSafe/gossamer: no Go files in ...` message when doing `go get`. This is not an error, since there are no go files in the project root. + +**3. Link your local clone to the fork on your Github repo.** + +``` +$ git remote add your-gossamer-repo https://github.com//gossamer.git +``` + +**4. Link your local clone to the ChainSafe Systems repo so that you can easily fetch future changes to the ChainSafe Systems repo.** + +``` +$ git remote add gossamer https://github.com/ChainSafe/gossamer.git +$ git remote -v (you should see myrepo and gossamer in the list of remotes) +``` + +**5. Find something to work on.** + +To start, check out our open issues. We recommend starting with an [issue labeled `Good First Issue`](https://github.com/ChainSafe/gossamer/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22). Leave a comment to let us know that you would like to work on it. + +Another option is to improve gossamer where you see fit based on your evaluation of our code. In order to best faciliate collaboration, please create an issue before you start working on it. + +**6. Make improvements to the code.** + +Each time you work on the code be sure that you are working on the branch that you have created as opposed to your local copy of the gossamer repo. Keeping your changes segregated in this branch will make it easier to merge your changes into the repo later. + +``` +$ git checkout feature-in-progress-branch +``` + +**7. Test your changes.** + +Changes that only affect a single file can be tested with + +``` +$ go test +``` + +**8. Lint your changes.** + +Before opening a pull request be sure to run the linter + +``` +$ gometallinter ./... +``` + +**9. Create a pull request.** + +Navigate your browser to [https://github.com/ChainSafe/gossamer](https://github.com/ChainSafe/gossamer) and click on the new pull request button. In the “base” box on the left, change the branch to “**base development**”, the branch that you want your changes to be applied to. In the “compare” box on the right, select feature-in-progress-branch, the branch containing the changes you want to apply. You will then be asked to answer a few questions about your pull request. After you complete the questionnaire, the pull request will appear in the list of pull requests at [https://github.com/ChainSafe/gossamer/pulls](https://github.com/ChainSafe/gossamer/pulls). + +## Note on memory intensive tests +Unfortunately, the free tier for CI's have a memory cap and some tests will cause the CI to experience an out of memory error. +In order to mitigate this we have introduced the concept of **short tests**. If your PR causes an out of memory error please seperate the tests into two groups +like below and make sure to label it `large`: + +``` +var stringTest = []string { + "This causes no leaks" +} + +var largeStringTest = []string { + "Whoa this test is so big it causes an out of memory issue" +} + +func TestStringTest(t *testing.T) { + ... +} + +func TestLargeStringTest(t *testing.T) { + if testing.Short() { + t.Skip("\033[33mSkipping memory intesive test for in short mode\033[0m") + } else { + ... + } +} +``` + +## Contributor Responsibilities + +We consider two types of contributions to our repo and categorize them as follows: + +### Part-Time Contributors + +Anyone can become a part-time contributor and help out on gossamer. Contributions can be made in the following ways: + +- Engaging in Discord conversations, asking questions on how to contribute to the project +- Opening up Github issues to contribute ideas on how the code can be improved +- Opening up PRs referencing any open issue in the repo. PRs should include: + - Detailed context of what would be required for merge + - Tests that are consistent with how other tests are written in our implementation +- Proper labels, milestones, and projects (see other closed PRs for reference) +- Follow up on open PRs + - Have an estimated timeframe to completion and let the core contributors know if a PR will take longer than expected + +We do not expect all part-time contributors to be experts on all the latest Polkadot documentation, but all contributors should at least be familiarized with the fundamentals of the [Polkadot Runtime Specification](https://research.web3.foundation/en/latest/_static/pdfview/viewer.html?file=../pdf/polkadot_re_spec.pdf). + +### Core Contributors + +Core contributors are currently comprised of members of the ChainSafe Systems team. Core devs have all of the responsibilities of part-time contributors plus the majority of the following: + +- Participate in our software development process (standups, sprint planning, retrospectives, etc) +- Stay up to date on the latest Polkadot research and updates +- Commit high quality code on core functionality +- Monitor github issues and PR’s to make sure owner, labels, descriptions are correct +- Formulate independent ideas, suggest new work to do, point out improvements to existing approaches +- Participate in code review, ensure code quality is excellent, and ensure high code coverage diff --git a/docs/docs/getting-started/installation.md b/docs/docs/getting-started/installation.md new file mode 100644 index 0000000000..b25d04197a --- /dev/null +++ b/docs/docs/getting-started/installation.md @@ -0,0 +1,121 @@ +--- +layout: default +title: Installation +permalink: /getting-started/installation +--- + +# Get Started + +## Prerequisites + +Install Go version `>=1.15` + +## Installation + +Get the ChainSafe/gossamer repository: +``` +git clone git@github.com:ChainSafe/gossamer +cd gossamer +``` + +Run the following command to build the Gossamer binary: +``` +make gossamer +``` + +## Run a Gossamer Node + +To run default Gossamer node, first initialize the node. This writes the genesis state to the database. +``` +./bin/gossamer --chain gssmr init +``` + +The gossamer node runs as an authority by default. The built-in authorities are `alice`, `bob`, `charlie`, `dave`, `eve`, `ferdie`, `george`, and `ian`. To start the node as an authority, provide it with a built-in key: +``` +./bin/gossamer --chain gssmr --key alice +``` + + +The node will not build blocks every slot by default; it will appear that the node is doing nothing, but it is actually waiting for a slot to build a block. If you wish to force it to build blocks every slot, you update the `[core]` section of `chain/gssmr/config.toml` to the following: + +``` +[core] +roles = 4 +babe-authority = true +grandpa-authority = true +babe-threshold-numerator = 1 +babe-threshold-denominator = 1 +``` + +Then, re-run the above steps. NOTE: this feature is for testing only; if you wish to change the BABE block production parameters, you need to create a modified runtime. + +If you wish to run the default node as a non-authority, you can specify `roles=1`: +``` +./bin/gossamer --chain gssmr --roles 1 +``` + +## Run Kusama Node + +To run a Kusama node, first initialise the node: +``` +./bin/gossamer --chain kusama init +``` + +Then run the node selecting the Kusama chain: +``` +./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/kusama/config.toml`: + +``` +[log] +network = "debug" +``` + +After it's finished bootstrapping, the node should begin to sync. + +## Run Polkadot Node + +Initialize polkadot node: +``` +./bin/gossamer --chain polkadot init +``` + +Start polkadot node: +``` +./bin/gossamer --chain polkadot +``` + +## Run Gossamer Node with Docker + +Gossamer can also be installed on GNU/Linux, MacOS systems with Docker. + +### Dependencies + +- Install the latest release of [Docker](https://docs.docker.com/get-docker/) + +Ensure you are running the most recent version of Docker by issuing the command: + +``` +docker -v +``` + +Pull the latest Gossamer images from DockerHub Registry: + +``` +docker pull chainsafe/gossamer:latest +``` + +The above command will install all required dependencies. + +Next, we need override the default entrypoint so we can run the node as an authority node + +``` +docker run -it --entrypoint /bin/bash chainsafe/gossamer:latest +``` + +The built-in authorities are `alice`, `bob`, `charlie`, `dave`, `eve`, `ferdie`, `george`, and `ian`. To start the node as an authority, provide it with a built-in key: +``` +./bin/gossamer --chain gssmr --key alice +``` diff --git a/docs/pages/Host_Architecture.md b/docs/docs/getting-started/overview/host-architecture.md similarity index 58% rename from docs/pages/Host_Architecture.md rename to docs/docs/getting-started/overview/host-architecture.md index da8d8677c3..ab147dcc51 100644 --- a/docs/pages/Host_Architecture.md +++ b/docs/docs/getting-started/overview/host-architecture.md @@ -4,10 +4,6 @@ title: Host Architecture permalink: /host-architecture/ --- -- _TODO: update "Host Architecture" document [#918](https://github.com/ChainSafe/gossamer/issues/918)_ - ---- - ## Nodes Gossamer includes a base node implementation called the **host node** that implements a shared base protocol for all blockchain protocols within the Polkadot ecosystem. The **host node** is used as the foundation for all **official nodes** within Gossamer and all **custom nodes** built with Gossamer. @@ -24,9 +20,9 @@ The **kusama node** is an official node implementation for the Kusama Network - The **polkadot node** is an official node implementation for the Polkadot Network - a configuration file, genesis file, compiled runtime, and runtime imports used with the **host node**. -### Custom Services + ## Node Services @@ -39,7 +35,7 @@ The **node services** are the main components of the **host node**: Each **node service** adheres to a common interface: -```go= +```go type Service interface { Start() error Stop() error @@ -52,7 +48,7 @@ type Service interface { ### Core Service -The **core service** is responsible for block production and finalization (consensus) and processing messages received from the **network service**; it initializes BABE sessions and GRANDPA rounds and validates blocks and transactions before committing them to the **state service**. +The **core service** is responsible for block production and finalization (consensus) and processing messages received from the **network service**; it initializes BABE sessions and GRANDPA rounds and validates blocks and transactions before committing them to the **state service**. - only the **core service** writes to block state - only the **core service** writes to storage state @@ -68,7 +64,7 @@ The **network service** is responsible for coordinating network host and peer in The **host submodule** is a wrapper for the libp2p host. This is used to abstract away the details of libp2p and to provide a simple reusable interface for the network host. -```go= +```go type host struct { ctx context.Context h libp2phost.Host @@ -78,80 +74,32 @@ type host struct { } ``` -#### Status Submodule - -The **status submodule** implements the protocol for the status message exchange. - -```go= -type status struct { - host *host - hostMessage *StatusMessage - peerConfirmed *sync.Map // map of peer.ID to time.Time - peerMessage *sync.Map // map of peer.ID to *StatusMessage -} -``` - -#### Gossip Submodule - -The **gossip submodule** stores information about past messages to effectively determine which messages to propagate and which to ignore. - -```go= -type gossip struct { - host *host - hasSeen *sync.Map -} -``` - -#### Syncer Submodule - -The **syncer submodule** tracks requested blocks and coordinates syncing with the **core service**. - -```go= -type syncer struct { - host *host - blockState BlockState - requestedBlockIDs *sync.Map // track requested block id messages - syncChan chan<- *big.Int // chain synchronization channel -} -``` ### RPC Service -The **rpc service** is an implementation of the RPC server. - -- the **rpc service** only reads from block state -- the **rpc service** only reads from storage state -- the **rpc service** only reads from network state +The **rpc service** is an implementation of the JSON-RPC PSP. ### State Service The **state service** is the source of truth for all chain and node state. -- only the **core service** writes to block state -- only the **core service** writes to storage state -- only the **network service** writes to network state - -## Node Channels -### Block Channels +## Block production -_work in progress_ +block production -### Message Channels +A block is broken down into two sections, **the header** & **the body**. -- `coreMsgs` - messages from the core service -- `networkMsgs` - messages from the network service +The first step is to get information about the parent block, for new blocks, this would be the head of the chain. -within the core service: +The **parent hash** and **state root** is added to the block header _(point 1 & 2)_ -- `msgSend` - send messages to the network service -- `msgRec` - receive messages from the network service +We then need to process the **extrinsics** _(point 3)_, extrinsics is used to describe any additional information to include in the block that isn't explicitly required to produce a block, such as **signed transactions** from accounts, or additional information added by the block author, like a **timestamp**. -within the network service: +Once processed, we get whats called an **extrinsic root** _(point 4)_, this is used to verify the extrinsics when publishing later on. -- `msgSend` - send messages to the core service -- `msgRec` - receive messages from the core service +Finally, once all the contents of the block are in place, we then create the **digest**_(point 5)_, this is used to verify the blocks contents. -### Syncer Channels +Information regarding the authoring of the block is stored in the **Babe header**, this allows verification of the block producer, the block, and the authority of the producer. -_work in progress_ +Finally, the last item of the digest, much like transactions, is a signature known as a **Seal**, this is a **signature of the header** to allow immediate verification of the integrity of a block. \ No newline at end of file diff --git a/docs/docs/getting-started/overview/package-library.md b/docs/docs/getting-started/overview/package-library.md new file mode 100644 index 0000000000..347a3caaf3 --- /dev/null +++ b/docs/docs/getting-started/overview/package-library.md @@ -0,0 +1,132 @@ +--- +layout: default +title: Package Library +permalink: /welcome/package-library/ +--- + +## Overview + +Gossamer is a **modular blockchain framework**; it was designed with a package structure that makes it possible to reuse Gossamer packages to build and run custom nodes and node services. + +This document provides an overview of the packages that make up the Gossamer framework - more detailed information about each package can be found at pkg.go.dev/ChainSafe/gossamer. + +Gossamer packages can be categorized into **four package types**: + +- **[cmd packages](#cmd-packages)** + + - `cmd/...` - command-line packages for running nodes and other services + +- **[host packages](#host-packages)** + + - `host/...` - the host node package and host node service packages + +- **[lib packages](#lib-packages)** + + - `lib/...` - modular packages for building nodes and other services + +- **[test packages](#test-packages)** + + - `tests/...` - test packages for integration tests + +## cmd packages + +#### `cmd/gossamer` + +- The **gossamer package** is used to run nodes built with Gossamer. + +## dot packages + +#### `dot` + +- The **dot package** contains packages that implement the Polkadot Host spec. The **dot package** implements the [Host Node](/getting-started/overview/host-architecture#host-node); it is the base node implementation for all [Official Nodes](/getting-started/overview/host-architecture#official-nodes) and [Custom Services](/getting-started/overview/host-architecture#custom-services) built with Gossamer. + +#### `dot/core` + +- The **core package** implements the [Core Service](/getting-started/overview/host-architecture#core-service) - responsible for block production and block finalization (consensus) and processing messages received from the [Network Service](/getting-started/overview/host-architecture/#network-service). + +#### `dot/network` + +- The **network package** implements the [Network Service](/getting-started/overview/host-architecture/#network-service) - responsible for coordinating network host and peer interactions. It manages peer connections, receives and parses messages from connected peers and handles each message based on its type. + +#### `dot/state` + +- The **state package** implements the [State Service](/getting-started/overview/host-architecture#state-service) - the source of truth for all chain and node state that is made accessible to all node services. + +#### `dot/sync` + +- The **sync package** implements handling of blocks received from the network layer. + +#### `dot/rpc` + +- The **rpc package** implements the [RPC Service](/getting-started/overview/host-architecture#rpc-service) - an HTTP server that handles state interactions. + +#### `dot/types` + +- The **types package** implements types defined within the Polkadot Host specification. + +## lib packages + +#### `lib/babe` + +- the **babe package** implements the BABE block production algorithm. + +#### `lib/blocktree` + +- the **blocktree package** implements the blocktree, a data structure which tracks the chain and all its non-finalized forks. + +#### `lib/common` + +- the **common package** defines common types and functions. + +#### `lib/crypto` + +- the **crypto package** contains the key types used by the node (sr25519, ed25519, secp256k1). + +#### `lib/grandpa` + +- the **grandpa package** implements the GRANDPA finality gadget. + +#### `lib/keystore` + +- the **keystore package** manages the keystore and includes test keyrings. + +#### `lib/runtime` + +- the **runtime package** contains various wasm interpreters used to interpret the runtime. It currently contains `life`, `wasmer`, and `wasmtime`; however, `wasmer` is the only interpreter that is fully supported at the moment. In the future, all interpreters will be fully supported. + +#### `lib/scale` + +- the **scale package** implements the SCALE codec. + +#### `lib/services` + +- the **services package** implements a common interface for node services. + +#### `lib/transaction` + +- the **transaction package** is contains transaction types and the transaction queue data structure. + +#### `lib/trie` + +- the **trie package** implements a modified merkle-patricia trie. + +#### `lib/utils` + +- the **utils package** is used to manage node and test directories. + +## test packages + +#### `tests/polkadotjs_test` +- the **polkadotjs_test section** is a node.js implementation to test interaction with Gossamer's RPC. + +#### `tests/rpc` +- the **rpc test collection** comprises tests to cover the RPC's various endpoints and return data. + +#### `tests/stress` +- the **stress test collection** comprises tests to simulate the node running under various high stress scenarios + +#### `tests/sync` +- the **sync test collection** comprises tests to verify the integrity of syncing operations and features + +#### `tests/utils` +- the **utils test collection** comprises tests to validate the function of various utilities throughout the Gossamer stack diff --git a/docs/docs/getting-started/resources/developer-resources.md b/docs/docs/getting-started/resources/developer-resources.md new file mode 100644 index 0000000000..6936b6c8cb --- /dev/null +++ b/docs/docs/getting-started/resources/developer-resources.md @@ -0,0 +1,61 @@ +--- +layout: default +title: Developer Resources +permalink: /developer-resources/ +--- + +### Specification + +- Polkadot Host Specification + +### Cryptography + +- blake2s used for hashing +- ed25519 (signing) +- ed25519 (curve) + +### Networking + +* W3F networking research +* libp2p Specs +* Kademlia (DHT) White Paper +* Kademlia Wiki Page + +### WASM + +- WASM Specification +- Wasm on the Blockchain: The Lesser Evil [blog post] + +### Polkadot + +- Polkadot Wiki +- Polkadot Consensus Wiki +- Polkadot Runtime Environment Specification (Section 8.2) +- Rust Docs: finality_grandpa +- paritytech/finality_grandpa +- The State of Crypto Interoperability Explained in Pictures + +#### Parachains + +- The Parachain (Blog Post) +- Parachains on Polkadot Wiki +- Parathreads (Blog Post) +- Parathreads on Polkadot Wiki +- The Path of a Parachain Block +- The Path of a Parachain Block (Video) + +#### Block production & consensus + +- BABE Specification +- GRANDPA Specification +- Polkadot Consensus Part 1: Introduction +- Polkadot Consensus Part 2: GRANDPA +- Polkadot Consensus Part 3: BABE +- Polkadot Consensus Part 4: Security +- Staking Diagram + +### Substrate + +- Official Substrate Documentation + + diff --git a/docs/docs/getting-started/resources/general-resources.md b/docs/docs/getting-started/resources/general-resources.md new file mode 100644 index 0000000000..56854b0644 --- /dev/null +++ b/docs/docs/getting-started/resources/general-resources.md @@ -0,0 +1,101 @@ +--- +layout: default +title: General Resources +permalink: /getting-started/resources/general-resources +--- + +## Welcome + +Here you will find resources to help facilitate your learning about _Polkadot_, the _Polkadot Host_, and _Gossamer_. Don't worry if you are unfamiliar with these terms, the resources listed here assume no prior knowledge about them. That being said, it would be helpful to have a basic understanding of existing blockchains such as Bitcoin and Ethereum. + +## Polkadot + +To start, it would be extremely beneficial to have an understanding of the Polkadot Network. For a high-level introduction to Polkadot, check out the lightpaper. To understand the motivation behind Polkadot's creation and what makes it unique, check out this great blog post A brief summary of everything Substrate and Polkadot. While reading, it would be helpful to note that Substrate and Gossamer are both implementations of the Polkadot Host. + +### Additional Resources + +#### Docs + +- Polkadot Wiki + +- Polkadot Paper + +#### Articles + +- How Polkadot tackles the biggest problems facing blockchain innovators - June 7th 2018 + +#### Block explorers + +- Polkadot Explorer + +- Polkascan - Polkadot block explorer + +- Polkadot Telemetry Service + +## Polkadot Host + +[_Please Note: The "Polkadot Host" was formerly known as the "Polkadot Runtime Enviornment"_] + +The Polkadot Host plays two important roles within the Polkadot ecosystem. + +- The Polkadot Host implements the **fundamental components for a blockchain**, ie networking and consensus. These components are not expected to change, and as such, they host part of the blockchain that is expected to change, the Runtime. For more details, check out Polkadot Host. + +- The Polkadot Host is **a blockchain development framework**, similar to how React and Angular are web development frameworks, but rather than helping developers build web applications, implementations of the Polkadot Host help developers build blockchains. + +As mentioned above, both Substrate and Gossamer are implementations of the Polkadot Host. If you're interested in the nitty-gritty technical details, check out the Polkadot Host specification. + +## Gossamer + +Gossamer is an implementation of the Polkadot Host in Go. To learn more about Gossamer, we recommend the following resources: + +- To understand the vision behind Gossamer and how it fits into the Polkadot ecosystem, please read this blog post: "The Future of Polkadot in Golang: Gossamer". + +- For a more technical explanation, we recommend watching this video. + +### Additional Resources + +#### Videos + +- Web3 Builders: ChainSafe - GoLang Implementation of Polkadot Host + +#### Articles + +- Gossamer Update: Introducing Gossamer - March 20th 2019 + +- Gossamer Update: Merkle-Patricia Trie - June 5th 2019 + +- Towards a Better Internet: Web3, Polkadot, and Gossamer - September 25th, 2019 + +- Building the Future with Gossamer - October 23rd 2019 + +- ChainSafe Releases Go-Schnorrkel - January 23rd 2020 + +- The Future of Polkadot in Golang: Gossamer - February 24th 2020 + +## Substrate + +#### Docs + +- Substrate Documentation + +#### Videos + +- Gavin Wood on Substrate at Event Horizon 2018 + +- Rob Habermeier presents Parity Substrate + +#### Articles + +- What is Substrate? - July 9th 2018 + +- A brief summary of everything Substrate and Polkadot - March 18th 2019 + +## Web3 Foundation + +#### Docs + +- Web3 Foundation's General Grants Program + +#### Articles + +- Why Wy Need Web 3.0 - September 12th 2018 diff --git a/docs/docs/index.md b/docs/docs/index.md new file mode 100644 index 0000000000..82291f966d --- /dev/null +++ b/docs/docs/index.md @@ -0,0 +1,38 @@ +--- +layout: default +permalink: / +--- + +
+ Gossamer logo +
+ +## A Go Implementation of the Polkadot Host + +Gossamer is an implementation of the Polkadot Host: a framework used to build and run nodes for different blockchain protocols that are compatible with the Polkadot ecosystem. The core of the Polkadot Host is the wasm runtime which handles the logic of the chain. + +Gossamer includes node implementations for major blockchains within the Polkadot ecosystem and simplifies building node implementations for other blockchains. Runtimes built with Substrate can plug their runtime into Gossamer to create a node implementation in Go. + +***Gossamer Docs*** is an evolving set of documents and resources to help you understand Gossamer, the Polkadot ecosystem, and how to build and run nodes using Gossamer. + +- If you are new to Gossamer and the Polkadot ecosystem, we recommend starting with this video and then working your way through [General Resources](/getting-started/resources/general-resources/). + +- If you are already familiar with Gossamer and the Polkadot ecosystem, or you just want to dive in, head over to [Get Started](/getting-started/installation) to run your first node using Gossamer. + +- If you are looking to build a node with Gossamer, learn how Gossamer can be used to build and run custom node implementations using Gossamer as a framework (keep reading). + +## Framework + +Gossamer is a ***modular blockchain framework*** used to build and run nodes for different blockchain protocols within the Polkadot ecosystem. + +- The ***simplest*** way to use the framework is using the base node implementation with a custom configuration file (see [Configuration](/usage/configuration)). + +- The ***more advanced*** way to use the framework is using the base node implementation with a compiled runtime and custom runtime imports (see [Import Runtime](/usage/import-runtime)). + + + +Our primary focus has been an initial implementation of the Polkadot Host. Once we feel confident our initial implementation is fully operational and secure, we will expand the Gossamer framework to include a runtime library and other tools and services that will enable Go developers to build, test, and run custom-built blockchain protocols within the Polkadot ecosystem. + +## Connect + +Let us know if you have any feedback or ideas that might help us improve our documentation or if you have any resources that you would like to see added. If you are planning to use Gossamer or any of the Gossamer packages, please say hello! You can find us on Discord. diff --git a/docs/docs/integrate/connect-to-polkadot-js.md b/docs/docs/integrate/connect-to-polkadot-js.md new file mode 100644 index 0000000000..7c4d8b8cb2 --- /dev/null +++ b/docs/docs/integrate/connect-to-polkadot-js.md @@ -0,0 +1,46 @@ +--- +layout: default +title: Connect to Polkadot.js +permalink: /integrate/connect-to-polkadot-js/ +--- + +# Connecting to Polkadot.js + +To view your running Gossamer node with a UI, Polkadot has created a handy app, which you can use here: https://polkadot.js.org/apps/ + +If using Polkadot's hosted app, you will need to ensure your node has the `--rpc-external`, `--ws` & `--ws-external` flags, if you are running the app locally, just ensure the rpc & websocket servers are running (`--rpc` && `--ws`) + +For example: +``` +bin/gossamer --rpc --ws --wsport 8546 --rpcmods system,author,chain,state,account,rpc --key alice +``` + +### Connecting the app to your node + +You'll need to setup the polkadot.js/apps to use a custom endpoint to connect to your gossamer node. Open [polkadot.js.org/apps](https://polkadot.js.org/apps). + +Once you've opened the app in your browser, you should see it connected to the Polkadot network: + + + +In the top left hand corner, click the logo to open the network selection modal: + + + +Next, at the bottom of this menu is a "Development" dropdown, click to open that + + + +Now you should see a text area with the label "custom endpoint", here you add your local node's websocket address, usually "ws://127.0.0.1:8586", +click the Save icon on the right of the text box to save the endpoint. + + + +Finally, click the "Switch" button at the top of this modal: + + + +Congratulations, you've successfully connected to your Gossamer node! + + + diff --git a/docs/docs/stylesheets/extra.css b/docs/docs/stylesheets/extra.css new file mode 100644 index 0000000000..88a6ef3d62 --- /dev/null +++ b/docs/docs/stylesheets/extra.css @@ -0,0 +1,7 @@ +[data-md-color-primary="pink"] { + --md-primary-fg-color: #e6087b; + --md-primary-fg-color--light: #ec417a; + --md-primary-fg-color--dark: #c3185d; + --md-primary-bg-color: #fff; + --md-primary-bg-color--light: hsla(0,0%,100%,0.7); +} \ No newline at end of file diff --git a/docs/docs/testing-and-debugging/debugging.md b/docs/docs/testing-and-debugging/debugging.md new file mode 100644 index 0000000000..abfe18c2d9 --- /dev/null +++ b/docs/docs/testing-and-debugging/debugging.md @@ -0,0 +1,28 @@ +--- +layout: default +title: Debugging +permalink: /testing-and-debugging/debugging +--- + +## Logger Commands + +The ```log``` command is used for setting the logging levels for the node. +## Config File +The logging level can be set using config.toml file, default log level will be set to info + +```[log] +core = "trace | debug | info | warn | error | crit" +sync = "trace | debug | info | warn | error | crit" +network = "trace | debug | info | warn | error | crit" +rpc = "trace | debug | info | warn | error | crit" +state = "trace | debug | info | warn | error | crit" +runtime = "trace | debug | info | warn | error | crit" +babe = "trace | debug | info | warn | error | crit" +grandpa = "trace | debug | info | warn | error | crit" +``` + +## Logging Global Flags +```--log value Supports levels crit (silent) to trce (trace) (default: "info")``` + +## Running node with log level as `DEBUG` +```./bin/gossamer --config chain/gssmr/config.toml --log debug``` diff --git a/docs/docs/testing-and-debugging/test-suite.md b/docs/docs/testing-and-debugging/test-suite.md new file mode 100644 index 0000000000..5e5c7ab31b --- /dev/null +++ b/docs/docs/testing-and-debugging/test-suite.md @@ -0,0 +1,65 @@ +--- +layout: default +title: Integration Tests +permalink: /testing-and-debugging/testing +--- + +## Gossamer Test Suite + +To run Gossamer unit tests run the following command: + +``` +make test +``` + +The above command will run all tests on project files with a timeout set for 20 minutes, and generate a coverage report in root `c.out`. + +You can view the coverage report through HTML by running the below command after running the above unit tests, or by visiting our [code coverage report here](https://app.codecov.io/gh/ChainSafe/gossamer). + +``` +go tool cover -html=c.out -o cover.html +``` + +Proceed to open `cover.html` in your preferred browser. + +### Gossamer Integration Tests + +Running Gossamer's integration tests with the below commands will build a Gossamer binary, install required dependencies, and then proceeds to run the provided set of tests. Integration tests can also be run within a docker container. + + +To run Gossamer integration tests in **stable** mode run the following command: + +``` +make it-stable +``` + +To run Gossamer integration tests in **stress** mode run the following command: + +``` +make it-stress +``` + +To run Gossamer integration tests against **GRANDPA** in stress mode run the following command: + +``` +make it-grandpa +``` + +To run Gossamer **RPC** integration tests run the following command: + +``` +make it-rpc +``` + +To run Gossamer **Sync** integration tests run the following command: + +``` +make it-sync +``` + +To run Gossamer **Polkadot.js** integration tests run the following command: + +``` +make it-polkadotjs +``` + diff --git a/docs/pages/Command-Line.md b/docs/docs/usage/command-line.md similarity index 77% rename from docs/pages/Command-Line.md rename to docs/docs/usage/command-line.md index 5e52509a7d..1d3918c519 100644 --- a/docs/pages/Command-Line.md +++ b/docs/docs/usage/command-line.md @@ -1,52 +1,64 @@ --- layout: default title: Command-Line -permalink: /command-line/ ---- - -- _TODO: update "Command-Line" document [#868](https://github.com/ChainSafe/gossamer/issues/868)_ - +permalink: /usage/command-line/ --- ## Gossamer Command The `gossamer` command is the root command for the `gossamer` package (`cmd/gossamer`). The root command starts the node (and initializes the node if the node has not already been initialized). -The `gossamer` command accepts the following ***local flags*** and ***global flags***: +### Accepted Formats ``` ---log value Supports levels crit (silent) to trce (trace) (default: "info") ---name value Node implementation name +gossamer [--global-flags] [--local-flags] +``` + +``` +gossamer [--local-flags] [--global-flags] +``` + +### Global flags + +The global flags can be used in conjunction with any Gossamer command + +``` +--basepath value Data directory for the node --chain value Node implementation id used to load default node configuration --config value TOML configuration file ---base-path value Data directory for the node +--cpuprof File to write CPU profile to +--log value Supports levels crit (silent) to trce (trace) (default: "info") +--memprof File to write memory profile to +--name value Node implementation name +--rewind value Rewind head of chain by given number of blocks +``` + +### Local flags + +These are the local flags that can be used with the `gossamer` command + +``` +--bootnodes value Comma separated enode URLs for network discovery bootstrap --key value Specify a test keyring account to use: eg --key=alice ---unlock value Unlock an account. eg. --unlock=0,2 to unlock accounts 0 and 2. Can be used with --password=[password] to avoid prompt. For multiple passwords, do --password=password1,password2 +--help, -h show help +--nobootstrap Disables network bootstrapping (mdns still enabled) +--nomdns Disables network mdns discovery --port value Set network listening port (default: 0) ---bootnodes value Comma separated enode URLs for network discovery bootstrap --protocol value Set protocol id --roles value Roles of the gossamer node ---nobootstrap Disables network bootstrapping (mdns still enabled) ---nomdns Disables network mdns discovery --rpc-external Enable the external HTTP-RPC server --rpchost value HTTP-RPC server listening hostname --rpcport value HTTP-RPC server listening port (default: 0) --rpcmods value API modules to enable via HTTP-RPC, comma separated list +--unlock value Unlock an account. + eg. --unlock=0,2 to unlock accounts 0 and 2. + Can be used with --password=[password] to avoid prompt. + For multiple passwords, do --password=password1,password2 --ws-external Enable the external websockets server --wsport value Websockets server listening port (default: 0) ---help, -h show help --version, -v print the version ``` -### Accepted Formats - -``` -gossamer [--global-flags] [--local-flags] -``` - -``` -gossamer [--local-flags] [--global-flags] -``` ## Gossamer Subcommands @@ -54,10 +66,10 @@ List of available ***subcommands***: ``` SUBCOMMANDS: - help, h Shows a list of commands or help for one command - account Create and manage node keystore accounts - export Export configuration values to TOML configuration file - init Initialize node databases and load genesis data to state + help, h Shows a list of commands or help for one command + account Create and manage node keystore accounts + export Export configuration values to TOML configuration file + init Initialize node databases and load genesis data to state ``` List of ***local flags*** for `init` subcommand: @@ -65,11 +77,6 @@ List of ***local flags*** for `init` subcommand: ``` --force Disable all confirm prompts (the same as answering "Y" to all) --genesis value Path to genesis JSON file ---log value Supports levels crit (silent) to trce (trace) (default: "info") ---name value Node implementation name ---chain value Node implementation id used to load default node configuration ---config value TOML configuration file ---base-path value Data directory for the node ``` List of ***local flags*** for `account` subcommand: @@ -78,15 +85,11 @@ List of ***local flags*** for `account` subcommand: --generate Generate a new keypair. If type is not specified, defaults to sr25519 --password value Password used to encrypt the keystore. Used with --generate or --unlock --import value Import encrypted keystore file generated with gossamer +--import-raw value Imports a raw private key --list List node keys --ed25519 Specify account type as ed25519 --sr25519 Specify account type as sr25519 --secp256k1 Specify account type as secp256k1 ---log value Supports levels crit (silent) to trce (trace) (default: "info") ---name value Node implementation name ---chain value Node implementation id used to load default node configuration ---config value TOML configuration file ---base-path value Data directory for the node ``` List of ***local flag*** options for `export` subcommand: @@ -94,11 +97,6 @@ List of ***local flag*** options for `export` subcommand: ``` --force Disable all confirm prompts (the same as answering "Y" to all) --genesis value Path to genesis JSON file ---log value Supports levels crit (silent) to trce (trace) (default: "info") ---name value Node implementation name ---chain value Node implementation id used to load default node configuration ---config value TOML configuration file ---base-path value Data directory for the node --key value Specify a test keyring account to use: eg --key=alice --unlock value Unlock an account. eg. --unlock=0,2 to unlock accounts 0 and 2. Can be used with --password=[password] to avoid prompt. For multiple passwords, do --password=password1,password2 --port value Set network listening port (default: 0) diff --git a/docs/docs/usage/configuration.md b/docs/docs/usage/configuration.md new file mode 100644 index 0000000000..57979672c6 --- /dev/null +++ b/docs/docs/usage/configuration.md @@ -0,0 +1,57 @@ +--- +layout: default +title: Configuration +permalink: /usage/configuration/ +--- + +# Configuration + +Gossamer consumes a `.toml` file containing predefined settings for the node from setting the genesis file, to the RPC/WS server, this file allows you to curated the functionality of the node instead of writing out the flags manually + +## Full reference + +```toml +[global] +basepath = "~/.gossamer/gssmr" // TODO: confirm +log = " | trace | debug | info | warn | error | crit" +cpuprof = "~/cpuprof.txt" // TODO: Syntax? +memprof = "~/memprof.txt" // TODO: Syntax? +name = "gssmr" + +[log] +core = " | trace | debug | info | warn | error | crit" +network = " | trace | debug | info | warn | error | crit" +rpc = " | trace | debug | info | warn | error | crit" +state = " | trace | debug | info | warn | error | crit" +runtime = " | trace | debug | info | warn | error | crit" +babe = " | trace | debug | info | warn | error | crit" +grandpa = " | trace | debug | info | warn | error | crit" +sync = " | trace | debug | info | warn | error | crit" + +[init] +genesis-raw = "./chain/gssmr/genesis-raw.json" + +[account] +key = "" +unlock = "" + +[core] +roles = 4 +babe-authority = true +grandpa-authority = true + +[network] +port = 7001 +nobootstrap = false +nomdns = false + +[rpc] +enabled = true | false +external = true | false +port = 8545 +host = "localhost" +modules = ["system", "author", "chain", "state", "rpc", "grandpa"] +ws = true | false +ws-external = true | false +ws-port = 8546 +``` \ No newline at end of file diff --git a/docs/docs/usage/import-runtime.md b/docs/docs/usage/import-runtime.md new file mode 100644 index 0000000000..7bed1f04cd --- /dev/null +++ b/docs/docs/usage/import-runtime.md @@ -0,0 +1,55 @@ +--- +layout: default +title: Import Runtime +permalink: /usage/import-runtime/ +--- + +# Launching a chain with a custom runtime + +The main use-case of the Polkadot Host is to create a standalone chain that may be converted to a parachain later. To do this, you need to have a compiled wasm runtime available for your chain. This can be created using [FRAME](https://substrate.dev/docs/en/knowledgebase/runtime/frame), a domain-specific language used for creating runtimes. + +Once you have your runtime ready and compiled into a wasm binary, it is ready to be used with Gossamer. + +### 1. Create genesis spec file with custom runtime + +You can use the `gossamer import-runtime` subcommand to create a genesis file containin g your custom runtime. The rest of the file is based off the `gssmr` `genesis.json` file. + +``` +make gossamer +./bin/gossamer import-runtime > genesis-spec.json +``` + +This creates a genesis spec file `genesis-spec.json` with the contents of your given file as the `"system"` `"code"` field. + +By default, `genesis-spec.json` will contain the 9 built-in keys as authorities with some preset balance. You can edit the fields as you wish. + +Note: the `import-runtime` subcommand does not validate that the runtime in the given file is valid. + +### 2. Create raw genesis file from genesis spec + +To create the raw genesis file used by the node, you can use the `gossamer build-spec` subcommand. + +``` +./bin/gossamer build-spec --raw --genesis genesis-spec.json > genesis.json +``` + +This creates a genesis file `genesis.json` that is usable by the node. + +### 3. Initialize the node with the genesis file + +Next, you will need to write the state in `genesis.json` to the database by initializing the node. + +``` +./bin/gossamer init --genesis genesis.json +``` + +The default basepath is `~/.gossamer/gssmr`. If you wish you change this, you can specify the basepath with `--basepath `. + +### 4. Start the node + +The final step is to launch the node. This is the same as normal, providing a built-in authority key: +``` +./bin/gossamer --key alice +``` + +You now have a chain running a custom runtime! \ No newline at end of file diff --git a/docs/docs/usage/import-state.md b/docs/docs/usage/import-state.md new file mode 100644 index 0000000000..38496bf107 --- /dev/null +++ b/docs/docs/usage/import-state.md @@ -0,0 +1,52 @@ +--- +layout: default +title: Import Sate +permalink: /usage/import-state/ +--- + +# Gossamer state import + +## Importing state + +Gossamer supports the ability to import state exported from gossamer or substrate. To retrieve the state from an existing node, you will need to run the node in **archive** mode. For example, with Kusama: +``` +./target/release/polkadot --chain=kusama --pruning archive --rpc-methods unsafe --rpc-port 8545 +``` + +Since we will be using the RPC method `state_getPairs` which is marked `unsafe`, you will need to use the `--rpc-methods unsafe` option. + +Once the node has synced to the height you wish to export, you can export the state by first finding the block hash of the block you wish to export (can use polkascan.io) or RPC. For example, for block 1000: +``` +curl -H "Content-Type: application/json" -d '{"id":1, "jsonrpc":"2.0", "method": "chain_getBlockHash", "params":[1000]}' http://localhost:8545 +{"jsonrpc":"2.0","result":"0xcf36a1e4a16fc579136137b8388f35490f09c5bdd7b9133835eba907a8b76c30","id":1} +``` + +For the following steps, you will need `jq` installed. + +Then, you can get the state at that block and redirect the output to a file `state.json`: +``` +curl -H "Content-Type: application/json" -d '{"id":1, "jsonrpc":"2.0", "method": "state_getPairs", "params":["0x", "0xcf36a1e4a16fc579136137b8388f35490f09c5bdd7b9133835eba907a8b76c30"]}' http://localhost:8545 | jq '.result' > state.json +``` + +Then, get the header of the block: +``` +curl -H "Content-Type: application/json" -d '{"id":1, "jsonrpc":"2.0", "method": "chain_getHeader", "params":["0xcf36a1e4a16fc579136137b8388f35490f09c5bdd7b9133835eba907a8b76c30"]}' http://localhost:8545 | jq '.result' > header.json +``` + +Lastly, get the first slot of the network. This can be find on polkascan.io. First, go to the network which you are importing then search for `1` (ie. block 1). Then, navigate to `Logs -> PreRuntime -> Details`. It will then show the `slotNumber`, for example, for Kusama, the first slot number is `262493679`: https://polkascan.io/kusama/log/1-0 + +Now you have all the required info to import the state into gossamer. + +In the `gossamer` directory: +``` +make gossamer +./bin/gossamer --chain init --force +./bin/gossamer import-state --chain --state state.json --header header.json --first-slot +``` + +If you don't want to use a specific chain, but instead a custom data directory, you can use `--basepath` instead of `--chain`. + +If it is successful, you will see a `finished state import` log. Now, you can start the node as usual, and the node should begin from the imported state: +``` +./bin/gossamer --chain +``` \ No newline at end of file diff --git a/docs/docs/usage/running-nodes.md b/docs/docs/usage/running-nodes.md new file mode 100644 index 0000000000..3d44568e49 --- /dev/null +++ b/docs/docs/usage/running-nodes.md @@ -0,0 +1,102 @@ +--- +layout: default +title: Running Nodes +permalink: /usage/running-nodes/ +--- + +## Run a Gossamer Node + +To run default Gossamer node, first initialize the node. This writes the genesis state to the database. +``` +./bin/gossamer --chain gssmr init +``` + +The gossamer node runs as an authority by default. The built-in authorities are `alice`, `bob`, `charlie`, `dave`, `eve`, `ferdie`, `george`, and `ian`. To start the node as an authority, provide it with a built-in key: +``` +./bin/gossamer --chain gssmr --key alice +``` + + +The node will not build blocks every slot by default; it will appear that the node is doing nothing, but it is actually waiting for a slot to build a block. If you wish to force it to build blocks every slot, you update the `[core]` section of `chain/gssmr/config.toml` to the following: + +``` +[core] +roles = 4 +babe-authority = true +grandpa-authority = true +babe-threshold-numerator = 1 +babe-threshold-denominator = 1 +``` + +Then, re-run the above steps. NOTE: this feature is for testing only; if you wish to change the BABE block production parameters, you need to create a modified runtime. + +If you wish to run the default node as a non-authority, you can specify `roles=1`: +``` +./bin/gossamer --chain gssmr --roles 1 +``` + +## Run Kusama Node + +To run a Kusama node, first initialise the node: +``` +./bin/gossamer --chain kusama init +``` + +Then run the node selecting the Kusama chain: +``` +./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/kusama/config.toml`: + +``` +[log] +network = "debug" +``` + +After it's finished bootstrapping, the node should begin to sync. + +## Run Polkadot Node + +Initialize polkadot node: +``` +./bin/gossamer --chain polkadot init +``` + +Start polkadot node: +``` +./bin/gossamer --chain polkadot +``` + +## Run Gossamer Node with Docker + +Gossamer can also be installed on GNU/Linux, MacOS systems with Docker. + +### Dependencies + +- Install the latest release of [Docker](https://docs.docker.com/get-docker/) + +Ensure you are running the most recent version of Docker by issuing the command: + +``` +docker -v +``` + +Pull the latest Gossamer images from DockerHub Registry: + +``` +docker pull chainsafe/gossamer:latest +``` + +The above command will install all required dependencies. + +Next, we need override the default entrypoint so we can run the node as an authority node + +``` +docker run -it --entrypoint /bin/bash chainsafe/gossamer:latest +``` + +The built-in authorities are `alice`, `bob`, `charlie`, `dave`, `eve`, `ferdie`, `george`, and `ian`. To start the node as an authority, provide it with a built-in key: +``` +./bin/gossamer --chain gssmr --key alice +``` diff --git a/docs/menus/Appendix.md b/docs/menus/Appendix.md deleted file mode 100644 index 911cd2823b..0000000000 --- a/docs/menus/Appendix.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -layout: default -title: Appendix -permalink: /appendix/ ---- - -- [SCALE Examples](../scale-examples/) diff --git a/docs/menus/Build_Nodes.md b/docs/menus/Build_Nodes.md deleted file mode 100644 index 3adbf7eb32..0000000000 --- a/docs/menus/Build_Nodes.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -layout: default -title: Build Nodes -permalink: /build-nodes/ ---- - -- [Configuration](../configuration/) - -- [Import Runtime](../import-runtime/) - -- [Custom Services](../custom-services/) - diff --git a/docs/menus/Implementation.md b/docs/menus/Implementation.md deleted file mode 100644 index beefaac847..0000000000 --- a/docs/menus/Implementation.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -layout: default -title: Implementation -permalink: /implementation/ ---- - -- [Package Library](../package-library/) - -- [Host Architecture](../host-architecture/) - -- [Integration Tests](../integration-tests/) diff --git a/docs/menus/Resources.md b/docs/menus/Resources.md deleted file mode 100644 index 21e645a111..0000000000 --- a/docs/menus/Resources.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -layout: default -title: Resources -permalink: /resources/ ---- - -- [General Resources](../general-resources/) - -- [Developer Resources](../developer-resources/) diff --git a/docs/menus/Run_Nodes.md b/docs/menus/Run_Nodes.md deleted file mode 100644 index d02ca818b4..0000000000 --- a/docs/menus/Run_Nodes.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -layout: default -title: Run Nodes -permalink: /run-nodes/ ---- - -- [Get Started](../get-started/) - -- [Command-Line](../command-line/) - -- [Official Nodes](../official-nodes/) diff --git a/docs/menus/index.md b/docs/menus/index.md new file mode 100644 index 0000000000..000ea3455f --- /dev/null +++ b/docs/menus/index.md @@ -0,0 +1,17 @@ +# Welcome to MkDocs + +For full documentation visit [mkdocs.org](https://www.mkdocs.org). + +## Commands + +* `mkdocs new [dir-name]` - Create a new project. +* `mkdocs serve` - Start the live-reloading docs server. +* `mkdocs build` - Build the documentation site. +* `mkdocs -h` - Print help message and exit. + +## Project layout + + mkdocs.yml # The configuration file. + docs/ + index.md # The documentation homepage. + ... # Other markdown pages, images and other files. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml new file mode 100644 index 0000000000..3ad3c27fa4 --- /dev/null +++ b/docs/mkdocs.yml @@ -0,0 +1,78 @@ +# Copyright 2020 ChainSafe Systems +# SPDX-License-Identifier: LGPL-3.0-only + +site_name: Gossamer Docs +site_description: The Official Documentation for Gossamer | A Go Implementation of the Polkadot Host + +repo_name: chainsafe/gossamer +repo_url: https://github.com/ChainSafe/gossamer + +# Configuration +markdown_extensions: + - meta + - admonition + - codehilite + - toc: + permalink: true + +theme: + name: material + palette: + primary: pink + accent: indigo + theme: + # Light mode + - media: "(prefers-color-scheme: light)" + scheme: default + primary: pink + accent: indigo + toggle: + icon: material/toggle-switch-off-outline + name: Switch to dark mode + + # Dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: pink + accent: indigo + toggle: + icon: material/toggle-switch + name: Switch to light mode + favicon: ./assets/favicon.ico + features: + # - navigation.instant + - navigation.tracking + - navigation.sections + - navigation.tabs + - navigation.tabs.sticky +nav: + - Getting Started: + - Overview: ./index.md + - Host Architecture: ./getting-started/overview/host-architecture.md + - Package Library: ./getting-started/overview/package-library.md + - Installation: ./getting-started/installation.md + - General Resources: ./getting-started/resources/general-resources.md + - Developer Resources: ./getting-started/resources/developer-resources.md + - Usage: + - Running Nodes: ./usage/running-nodes.md + - Command Line: ./usage/command-line.md + - Configuration: ./usage/configuration.md + - Import Runtime: ./usage/import-runtime.md + - Import State: ./usage/import-state.md + - Integrate: + - Connect to Polkadot.js: ./integrate/connect-to-polkadot-js.md + - Testing and Debugging: + - Test Suite: ./testing-and-debugging/test-suite.md + - Debugging: ./testing-and-debugging/debugging.md + - Advanced: + - SCALE Examples: ./advanced/scale-examples.md + - Contributing: + - Overview: ./contributing.md +extra_css: + - stylesheets/extra.css +extra: + social: + - icon: fontawesome/brands/github-alt + link: https://github.com/ChainSafe/gossamer + - icon: fontawesome/brands/twitter + link: https://twitter.com/ChainSafeth \ No newline at end of file diff --git a/docs/pages/Configuration.md b/docs/pages/Configuration.md deleted file mode 100644 index 974d7dba26..0000000000 --- a/docs/pages/Configuration.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -layout: default -title: Configuration -permalink: /configuration/ ---- - -- _TODO: update "Configuration" document [#867](https://github.com/ChainSafe/gossamer/issues/867)_ - ---- diff --git a/docs/pages/Custom_Services.md b/docs/pages/Custom_Services.md deleted file mode 100644 index 00f40f67c9..0000000000 --- a/docs/pages/Custom_Services.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -layout: default -title: Custom Services -permalink: /custom-services/ ---- - -- _TODO: update "Custom Services" document [#917](https://github.com/ChainSafe/gossamer/issues/917)_ - ---- diff --git a/docs/pages/Developer_Resources.md b/docs/pages/Developer_Resources.md deleted file mode 100644 index 179af579bb..0000000000 --- a/docs/pages/Developer_Resources.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -layout: default -title: Developer Resources -permalink: /developer-resources/ ---- - -### Specification - -- [Polkadot Host Specification](https://github.com/w3f/polkadot-spec/tree/master/host-spec) - -### Cryptography - -- [blake2s](https://godoc.org/golang.org/x/crypto/blake2s) used for hashing -- [ed25519 (signing)](https://godoc.org/golang.org/x/crypto/ed25519) -- [ed25519 (curve)](https://godoc.org/golang.org/x/crypto/ed25519/internal/edwards25519) - -### Networking - -* [W3F networking research](https://w3f-research.readthedocs.io/en/latest/polkadot/networking.html) -* [libp2p Specs](https://github.com/libp2p/specs) -* [Kademlia (DHT) White Paper](https://pdos.csail.mit.edu/~petar/papers/maymounkov-kademlia-lncs.pdf) -* [Kademlia Wiki Page](https://en.wikipedia.org/wiki/Kademlia) - -### WASM - -- [WASM Specification](https://webassembly.github.io/spec/core/index.html) -- [Wasm on the Blockchain: The Lesser Evil [blog post]](https://medium.com/polkadot-network/wasm-on-the-blockchain-the-lesser-evil-da8d7c6ef6bd) - -### Polkadot - -- [Polkadot Wiki](https://wiki.polkadot.network/en/) -- [Polkadot Consensus Wiki](https://wiki.polkadot.network/en/latest/polkadot/learn/consensus/) -- [Polkadot Runtime Specification (Section 8.2)](https://w3f-research.readthedocs.io/en/latest/polkadot/specifications/runtime.html) -- [Rust Docs: finality_grandpa](https://docs.rs/finality-grandpa/0.1.0/finality_grandpa/) -- [paritytech/finality_grandpa](https://github.com/paritytech/finality-grandpa) -- [The State of Crypto Interoperability Explained in Pictures](https://tokeneconomy.co/the-state-of-crypto-interoperability-explained-in-pictures-654cfe4cc167) - -**parachains** -- [The Parachain (Blog Post)](https://medium.com/polkadot-network/polkadot-the-parachain-3808040a769a) -- [Parachains on Polkadot Wiki](https://wiki.polkadot.network/docs/en/learn-parachains) -- [Parathreads (Blog Post)](https://polkadot.network/parathreads-parathreads-pay-as-you-go-parachains/) -- [Parathreads on Polkadot Wiki](https://wiki.polkadot.network/docs/en/learn-parathreads) -- [The Path of a Parachain Block](https://medium.com/polkadot-network/the-path-of-a-parachain-block-47d05765d7a) -- [The Path of a Parachain Block (Video)](https://www.youtube.com/watch?v=m0vxqWwFfDs) - -**block production & consensus** -- [BABE Specification](https://research.web3.foundation/en/latest/polkadot/block-production/Babe.html) -- [GRANDPA Specification](https://github.com/w3f/consensus/blob/master/pdf/grandpa.pdf) -- [Polkadot Consensus Part 1: Introduction](https://medium.com/polkadot-network/polkadot-consensus-part-1-introduction-3e3cd6237243) -- [Polkadot Consensus Part 2: GRANDPA](https://medium.com/polkadot-network/polkadot-consensus-part-2-grandpa-fb1963ef6c70) -- [Polkadot Consensus Part 3: BABE](https://medium.com/polkadot-network/polkadot-consensus-part-3-babe-dcc2e0dd8878) -- [Polkadot Consensus Part 4: Security](https://medium.com/polkadot-network/polkadot-consensus-part-4-security-eb3180b6d7e4) -- [Staking Diagram](https://matrix-client.matrix.org/_matrix/media/r0/download/web3.foundation/cREGRimorZepfWQKbsFLklRa) - -### Substrate - -- [Official Substrate Documentation](https://substrate.dev/en/) - diff --git a/docs/pages/General_Resources.md b/docs/pages/General_Resources.md deleted file mode 100644 index 0d56a6eb26..0000000000 --- a/docs/pages/General_Resources.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -layout: default -title: General Resources -permalink: /general-resources/ ---- - -## Welcome - -Here you will find resources to help facilitate your learning about _Polkadot_, the _Polkadot Host_, and _Gossamer_. Don't worry if you are unfamiliar with these [terms](https://github.com/ChainSafe/gossamer/wiki/Resources/), the resources listed here assume no prior knowledge about them. That being said, it would be helpful to have a basic understanding of existing blockchains such as Bitcoin and Ethereum. - -## Polkadot - -To start, it would be extremely beneficial to have an understanding of the Polkadot Network. For a high-level introduction to Polkadot, check out the [lightpaper](https://polkadot.network/Polkadot-lightpaper.pdf). To understand the motivation behind Polkadot's creation and what makes it unique, check out this great blog post: ["A brief summary of everything Substrate and Polkadot"](https://medium.com/polkadot-network/a-brief-summary-of-everything-substrate-and-polkadot-f1f21071499d). While reading, it would be helpful to note that [Substrate](https://github.com/paritytech/substrate) and [Gossamer](https://github.com/ChainSafe/gossamer) are both implementations of the Polkadot Host. - -### Additional Resources - -#### docs - -- [Polkadot Wiki](https://wiki.polkadot.network/en/) - -- [Polkadot Paper](https://polkadot.network/PolkaDotPaper.pdf) - -#### articles - -- [How Polkadot tackles the biggest problems facing blockchain innovators](https://medium.com/polkadot-network/how-polkadot-tackles-the-biggest-problems-facing-blockchain-innovators-1affc1309b0f) - June 7th 2018 - -#### block explorers - -- [Polkadot Explorer](https://polkadot.js.org/apps/#/explorer) - -- [Polkascan](https://polkascan.io/) - Polkadot block explorer - -- [Polkadot Telemetry Service](https://telemetry.polkadot.io/#/Kusama) - -## Polkadot Host - -[_Please Note: The "Polkadot Host" was formerly known as the "Polkadot Runtime Enviornment"_] - -The Polkadot Host plays two important roles within the Polkadot ecosystem. - -- The Polkadot Host implements the **fundamental components for a blockchain**, ie networking and consensus. These components are not expected to change, and as such, they host part of the blockchain that is expected to change, the Runtime. For more details, check out [Polkadot Host](https://wiki.polkadot.network/docs/en/learn-polkadot-host). - -- The Polkadot Host is **a blockchain development framework**, similar to how React and Angular are web development frameworks, but rather than helping developers build web applications, implementations of the Polkadot Host help developers build blockchains. - -As mentioned above, both [Substrate](https://github.com/paritytech/substrate) and [Gossamer](https://github.com/ChainSafe/gossamer) are implementations of the Polkadot Host. If you're interested in the nitty-gritty technical details, check out the [Polkadot Host specification](https://github.com/w3f/polkadot-spec/blob/master/polkadot-host-spec/polkadot_host_spec.pdf). - -## Gossamer - -Gossamer is an implementation of the Polkadot Host in Go. To learn more about Gossamer, we recommend the following resources: - -- To understand the vision behind Gossamer and how it fits into the Polkadot ecosystem, please read this blog post: ["The Future of Polkadot in Golang: Gossamer"](https://medium.com/chainsafe-systems/the-future-of-polkadot-in-golang-gossamer-3345f0d6143d). - -- For a more technical explanation, we recommend watching this [video](https://medium.com/chainsafe-systems/the-future-of-polkadot-in-golang-gossamer-3345f0d6143d). - -### Additional Resources - -#### videos - -- [Web3 Builders: ChainSafe - GoLang Implementation of Polkadot Host](https://www.youtube.com/watch?v=vqluOY-ysFI) - -#### articles - -- [Gossamer Update: Introducing Gossamer](https://medium.com/chainsafe-systems/gossamer0-2ccf51ad0c91) - March 20th 2019 - -- [Gossamer Update: Merkle-Patricia Trie](https://medium.com/chainsafe-systems/gossamer-update-1-merkle-patricia-trie-6320588efedd) - June 5th 2019 - -- [Towards a Better Internet: Web3, Polkadot, and Gossamer](https://medium.com/chainsafe-systems/towards-a-better-internet-web3-polkadot-and-gossamer-68eb559dd2c5) - September 25th, 2019 - -- [Building the Future with Gossamer](https://medium.com/chainsafe-systems/building-the-future-with-gossamer-ccb8c4530299) - October 23rd 2019 - -- [ChainSafe Releases Go-Schnorrkel](https://medium.com/chainsafe-systems/chainsafe-releases-go-schnorrkel-487b6b5e3b87) - January 23rd 2020 - -- [The Future of Polkadot in Golang: Gossamer](https://medium.com/chainsafe-systems/the-future-of-polkadot-in-golang-gossamer-3345f0d6143d) - February 24th 2020 - -## Substrate - -#### docs - -- [Substrate Documentation](https://substrate.dev/en/) - -#### videos - -- [Gavin Wood on Substrate at Event Horizon 2018](https://www.youtube.com/watch?v=iUMZyL5kTwc&feature=youtu.be) - -- [Rob Habermeier presents Parity Substrate](https://www.youtube.com/watch?v=q1zLHO7Lkuk&feature=youtu.be) - -#### articles - -- [What is Substrate?](https://medium.com/paritytech/what-is-substrate-29af4231d7e0) - July 9th 2018 - -- [A brief summary of everything Substrate and Polkadot](https://medium.com/polkadot-network/a-brief-summary-of-everything-substrate-and-polkadot-f1f21071499d) - March 18th 2019 - -## Web3 Foundation - -#### docs - -- Web3 Foundation's [General Grants Program](https://github.com/w3f/General-Grants-Program) - -#### articles - -- [Why Wy Need Web 3.0](https://medium.com/@gavofyork/why-we-need-web-3-0-5da4f2bf95ab) - September 12th 2018 diff --git a/docs/pages/Get_Started.md b/docs/pages/Get_Started.md deleted file mode 100644 index 48b9100c51..0000000000 --- a/docs/pages/Get_Started.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -layout: default -title: Get Started -permalink: /get-started/ ---- - -## Prerequisites - -install go version `>=1.13` - -## Installation - -get the [ChainSafe/gossamer](https://github.com/ChainSafe/gossamer) repository: -``` -go get -u github.com/ChainSafe/gossamer -``` - -build gossamer command: -``` -make gossamer -``` - -## Run Default Node - -initialize default node: -``` -./bin/gossamer --key alice init -``` - -start default node: -``` -./bin/gossamer --key alice -``` - -## Run Gossamer Node - -initialize gossamer node: -``` -./bin/gossamer --chain gssmr --key alice init -``` - -start gossamer node: -``` -./bin/gossamer --chain gssmr --key alice -``` - -## Run Kusama Node (_in development_) - -initialize kusama node: -``` -./bin/gossamer --chain kusama --key alice init -``` - -start kusama node: -``` -./bin/gossamer --chain kusama --key alice -``` - -## Run Polkadot Node (_in development_) - -initialize polkadot node: -``` -./bin/gossamer --chain dotcc --key alice init -``` - -start polkadot node: -``` -./bin/gossamer --chain dotcc --key alice -``` diff --git a/docs/pages/Import_Runtime.md b/docs/pages/Import_Runtime.md deleted file mode 100644 index 4a559af742..0000000000 --- a/docs/pages/Import_Runtime.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -layout: default -title: Import Runtime -permalink: /import-runtime/ ---- - -- _TODO: update "Import Runtime" document [#869](https://github.com/ChainSafe/gossamer/issues/869)_ - ---- diff --git a/docs/pages/Index.md b/docs/pages/Index.md deleted file mode 100644 index 1e9021edf2..0000000000 --- a/docs/pages/Index.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -layout: default -permalink: / ---- - -
- Gossamer logo -
-
-

Gossamer Docs | The Official Documentation for Gossamer

-
-
- -## Welcome - -***Gossamer*** is an implementation of the [Polkadot Host](https://github.com/w3f/polkadot-spec) - a blockchain framework used to build and run nodes for different blockchain protocols within the Polkadot ecosystem. - -Gossamer includes node implementations for major blockchains within the Polkadot ecosystem and makes building node implementations for other blockchains trivial; blockchains built with [Substrate](https://github.com/paritytech/substrate) can plug their compiled runtime into Gossamer to create a node implementation in Go. - -***Gossamer Docs*** is an evolving set of documents and resources to help you understand Gossamer, the Polkadot ecosystem, and how to build and run nodes using Gossamer. - -- If you are new to Gossamer and the Polkadot ecosystem, we recommend starting with [this video](https://www.youtube.com/watch?v=nYkbYhM5Yfk) and then working your way through [General Resources](./general-resources/). - -- If you are already familiar with Gossamer and the Polkadot ecosystem, or you just want to dive in, head over to [Get Started](./get-started) to run your first node using Gossamer. - -- If you are looking to build a node with Gossamer, learn how Gossamer can be used to build and run custom node implementations using Gossamer as a framework (keep reading). - -## Framework - -Gossamer is a ***modular blockchain framework*** used to build and run nodes for different blockchain protocols within the Polkadot ecosystem. - -- The ***simplest*** way to use the framework is using the base node implementation with a custom configuration file (see [Configuration](./configuration/)). - -- The ***more advanced*** way to use the framework is using the base node implementation with a compiled runtime and custom runtime imports (see [Import Runtime](./import-runtime/)). - -- The ***most advanced*** way to use the framework is building custom node services or a custom node implementation (see [Custom Services](./custom-services/)). - -Our primary focus has been an initial implementation of the Polkadot Host. Once we feel confident our initial implementation is fully operational and secure, we will expand the Gossamer framework to include a runtime library and other tools and services that will enable Go developers to build, test, and run custom-built blockchain protocols within the Polkadot ecosystem. - -## Table of Contents - -- **[Run Nodes](./run-nodes/)** - - [Get Started](./get-started/) - - [Command-Line](./command-line/) - - [Official Nodes](./official-nodes/) - -- **[Build Nodes](./build-nodes/)** - - [Configuration](./configuration/) - - [Import Runtime](./import-runtime/) - - [Custom Services](./custom-services/) - -- **[Implementation](./implementation/)** - - [Package Library](./package-library/) - - [Host Architecture](./host-architecture/) - - [Integration Tests](./integration-tests/) - -- **[Resources](./resources/)** - - [General Resources](./general-resources/) - - [Developer Resources](./developer-resources/) - - - -## Connect - -Let us know if you have any feedback or ideas that might help us improve our documentation or if you have any resources that you would like to see added. If you are planning to use Gossamer or any of the Gossamer packages, please say hello! You can find us on [Discord](https://discord.gg/Xdc5xjE). - -## Contribute - -Contributions to this site and its contents are more than welcome. We built this site with [jekyll](https://jekyllrb.com/) - the site configuration and markdown files are within [gossamer/docs](https://github.com/ChainSafe/gossamer/tree/development/docs). If you would like to contribute, please read [Code of Conduct](https://github.com/ChainSafe/gossamer/blob/development/.github/CODE_OF_CONDUCT.md) and [Contributing Guidelines](https://github.com/ChainSafe/gossamer/blob/development/.github/CONTRIBUTING.md) before getting started. diff --git a/docs/pages/Integration_Tests.md b/docs/pages/Integration_Tests.md deleted file mode 100644 index 9a51be1512..0000000000 --- a/docs/pages/Integration_Tests.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -layout: default -title: Integration Tests -permalink: /integration-tests/ ---- - -- _TODO: update "Integration Tests" document [#710](https://github.com/ChainSafe/gossamer/issues/710)_ - ---- diff --git a/docs/pages/Official_Nodes.md b/docs/pages/Official_Nodes.md deleted file mode 100644 index 30239e870c..0000000000 --- a/docs/pages/Official_Nodes.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -layout: default -title: Official Nodes -permalink: /official-nodes/ ---- - -- _TODO: update "Official Nodes" document [#916](https://github.com/ChainSafe/gossamer/issues/916)_ - ---- - -## `chain/gssmr` - -- The **gssmr** directory includes configuration files for the ***gssmr node*** implementation - an official node implementation for the Gossamer Testnet (see [Official Nodes](../host-architecture#official-nodes)). - -## `chain/kusama` - -- The **kusama** directory includes configuration files for the ***kusama node*** implementation - an official node implementation for the Kusama Network (see [Official Nodes](../host-architecture#official-nodes)). - -## `chain/polkadot` - -- The **polkadot** directory includes configuration files for the ***polkadot node*** implementation - an official node implementation for the Polkadot Network (see [Official Nodes](../host-architecture#official-nodes)). diff --git a/docs/pages/Package_Library.md b/docs/pages/Package_Library.md deleted file mode 100644 index 5b04ba0a3b..0000000000 --- a/docs/pages/Package_Library.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -layout: default -title: Package Library -permalink: /package-library/ ---- - -## Overview - -Gossamer is a ***modular blockchain framework***; it was designed with a package structure that makes it possible to reuse Gossamer packages to build and run custom nodes and node services. - -This document provides an overview of the packages that make up the Gossamer framework - more detailed information about each package can be found at [pkg.go.dev/ChainSafe/gossamer](https://pkg.go.dev/github.com/ChainSafe/gossamer). - -Gossamer packages can be categorized into **four package types**: - -- **[cmd packages](#cmd-packages)** - - - `cmd/...` - _command packages for running nodes and other services_ - -- **[host packages](#host-packages)** - - - `host/...` - _the host node package and host node service packages_ - -- **[lib packages](#lib-packages)** - - - `lib/...` - _modular packages for building nodes and other services_ - -- **[test packages](#test-packages)** - - - `tests/...` - _test packages for test framework (ie, integration tests)_ - -## cmd packages - -#### `cmd/gossaamer` - -- The **gossamer package** is used to run nodes built with Gossamer. - -## host packages - -#### `host` - -- The **host package** implements the shared base protocol for all node implementations operating within the Polkadot ecosystem. The **host package** implements the [Host Node](../host-architecture#host-node); it is the base node implementation for all [Official Nodes](../host-architecture#official-nodes) and [Custom Services](../host-architecture#custom-services) built with Gossamer. - -#### `host/core` - -- The **core package** implements the [Core Service](../host-architecture#core-service) - responsible for block production and block finalization (consensus) and processing messages received from the [Network Service](../host-architecture#network-service). - -#### `host/network` - -- The **network package** implements the [Network Service](../host-architecture#network-service) - responsible for coordinating network host and peer interactions. It manages peer connections, receives and parses messages from connected peers and handles each message based on its type. - -#### `host/state` - -- The **state package** implements the [State Service](../host-architecture#state-service) - the source of truth for all chain and node state that is made accessible to all node services. - -#### `host/rpc` - -- The **rpc package** implements the [RPC Service](../host-architecture#rpc-service) - an HTTP server that handles state interactions. - -#### `host/types` - -- The **types package** implements types defined within the Polkadot Host specification. - -## lib packages - -#### `lib/babe` - -- the **babe package** implements BABE - -#### `lib/blocktree` - -- the **blocktree package** implements blocktree - -#### `lib/common` - -- the **common package** defines common types and functions - -#### `lib/crypto` - -- the **crypto package** implements crypto keypairs - -#### `lib/database` - -- the **database package** is a generic database built with badgerDB - -#### `lib/grandpa` - -- the **grandpa package** implements GRANDPA - -#### `lib/keystore` - -- the **keystore package** manages the keystore and includes test keyrings - -#### `lib/runtime` - -- the **runtime package** implements the WASM runtime using Wasmer - -#### `lib/scale` - -- the **scale package** implements the SCALE codec - -#### `lib/services` - -- the **services package** implements a common interface for node services - -#### `lib/transaction` - -- the **transaction package** is used to manage transaction queues - -#### `lib/trie` - -- the **trie package** implements a modified merkle-patricia trie - -#### `lib/utils` - -- the **utils package** is used to manage node and test directories