solana-docs 0.0.0

package/.eslintignore

@@ -0,0 +1,8 @@
+node_modules
+build
+static
+html
+
+# FIXME
+src/pages/index.js
+src/theme/Footer/index.js

package/.eslintrc

@@ -0,0 +1,21 @@
+{
+    "env": {
+      "browser": true,
+      "node": true
+    },
+    "parser": "babel-eslint",
+    "rules": {
+      "strict": 0,
+      "no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
+      "no-trailing-spaces": ["error", { "skipBlankLines": true }]
+    },
+    "settings": {
+      "react": {
+        "version": "detect", // React version. "detect" automatically picks the version you have installed.
+      }
+    },
+    "extends": [
+      "eslint:recommended",
+      "plugin:react/recommended"
+    ]
+  }

package/.prettierignore

@@ -0,0 +1,7 @@
+.docusaurus
+build
+html
+static
+
+# prettier interferes with the json response too much
+src/developing/clients/jsonrpc-api.md

package/.travis/before_install.sh

@@ -0,0 +1,9 @@
+# |source| this file
+
+curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash -
+sudo apt install -y nodejs
+
+npm install --global docusaurus-init
+docusaurus-init
+
+npm install --global vercel

package/.travis/script.sh

@@ -0,0 +1,4 @@
+# |source| this file
+
+set -ex
+./build.sh

package/README.md

@@ -0,0 +1,59 @@
+# Docs Readme
+
+Solana's Docs are built using [Docusaurus 2](https://v2.docusaurus.io/) with `npm`.
+Static content delivery is handled using `vercel`.
+
+### Installing Docusaurus
+
+```sh
+$ npm install
+```
+
+### Local Development
+
+This command starts a local development server and opens up a browser window.
+Most changes are reflected live without having to restart the server.
+(You might have to run build.sh first if you run into failures)
+
+```sh
+$ npm run start
+```
+
+### Build Locally
+
+This command generates static content into the `build` directory and can be
+served using any static content hosting service.
+
+```sh
+$ docs/build.sh
+```
+
+### Translations
+
+Translations are sourced from [Crowdin](https://docusaurus.io/docs/i18n/crowdin)
+and generated when master is built.
+For local development use the following two commands in the `docs` directory.
+
+To download the newest Documentation translations run:
+
+```sh
+npm run crowdin:download
+```
+
+To upload changes from `src` & generate [explicit IDs](https://docusaurus.io/docs/markdown-features/headings#explicit-ids):
+
+```shell
+npm run crowdin:upload
+```
+
+### CI Build Flow
+
+The docs are built and published in Travis CI with the `docs/build.sh` script.
+On each PR, the docs are built, but not published.
+
+In each post-commit build, docs are built and published using `vercel` to their
+respective domain depending on the build branch.
+
+- Master branch docs are published to `edge.docs.solana.com`
+- Beta branch docs are published to `beta.docs.solana.com`
+- Latest release tag docs are published to `docs.solana.com`

package/art/data-plane-fanout.bob

@@ -0,0 +1,19 @@
++------------------------------------------------------------------+
+|                                                                  |
+|   +-----------------+    Neighborhood 0    +-----------------+   |
+|   |                 +--------------------->+                 |   |
+|   |   Validator 1   |                      |   Validator 2   |   |
+|   |                 +<---------------------+                 |   |
+|   +--------+-+------+                      +------+-+--------+   |
+|            | |                                    | |            |
+|            | +-----------------------------+      | |            |
+|            |      +------------------------+------+ |            |
+|            |      |                        |        |            |
++------------------------------------------------------------------+
+             |      |                        |        |
+             v      v                        v        v
+   +---------+------+---+                  +-+--------+---------+
+   |                    |                  |                    |
+   |   Neighborhood 1   |                  |   Neighborhood 2   |
+   |                    |                  |                    |
+   +--------------------+                  +--------------------+

package/art/data-plane-neighborhood.bob

@@ -0,0 +1,25 @@
++---------------------------------------------------------------------------------------------------------+
+|                                           Neighborhood Above                                            |
+|                                                                                                         |
+|      +----------------+       +----------------+       +----------------+       +----------------+      |
+|      |                +------>+                +------>+                +------>+                |      |
+|      |   Neighbor 1   |       |   Neighbor 2   |       |   Neighbor 3   |       |   Neighbor 4   |      |
+|      |                +<------+                +<------+                +<------+                |      |
+|      +--+-------------+       +--+-------------+       +-----+----------+       +--+-------------+      |
+|         |                        |                           |                     |                    |
++---------------------------------------------------------------------------------------------------------+
+          |                        |                           |                     |
+          |                        |                           |                     |
+          |                        |                           |                     |
+          |                        |                           |                     |
+          |                        |                           |                     |
++---------------------------------------------------------------------------------------------------------+
+|         |                        |        Neighborhood Below |                     |                    |
+|         v                        v                           v                     v                    |
+|      +--+-------------+       +--+-------------+       +-----+----------+       +--+-------------+      |
+|      |                +------>+                +------>+                +------>+                |      |
+|      |   Neighbor 1   |       |   Neighbor 2   |       |   Neighbor 3   |       |   Neighbor 4   |      |
+|      |                +<------+                +<------+                +<------+                |      |
+|      +----------------+       +----------------+       +----------------+       +----------------+      |
+|                                                                                                         |
++---------------------------------------------------------------------------------------------------------+

package/art/data-plane-seeding.bob

@@ -0,0 +1,15 @@
+                          +--------------+
+                          |              |
+             +------------+    Leader    +------------+
+             |            |              |            |
+             |            +--------------+            |
+             v                                        v
++------------+----------------------------------------+------------+
+|                                                                  |
+|   +-----------------+    Neighborhood 0    +-----------------+   |
+|   |                 +--------------------->+                 |   |
+|   |   Validator 1   |                      |   Validator 2   |   |
+|   |                 +<---------------------+                 |   |
+|   +-----------------+                      +-----------------+   |
+|                                                                  |
++------------------------------------------------------------------+

package/art/data-plane.bob

@@ -0,0 +1,18 @@
+                                  +--------------------+
+                                  |                    |
+                         +--------+   Neighborhood 0   +----------+
+                         |        |                    |          |
+                         |        +--------------------+          |
+                         v                                        v
+               +---------+----------+                  +----------+---------+
+               |                    |                  |                    |
+               |   Neighborhood 1   |                  |   Neighborhood 2   |
+               |                    |                  |                    |
+               +---+-----+----------+                  +----------+-----+---+
+                   |     |                                        |     |
+                   v     v                                        v     v
++------------------+-+ +-+------------------+  +------------------+-+ +-+------------------+
+|                    | |                    |  |                    | |                    |
+|   Neighborhood 3   | |   Neighborhood 4   |  |   Neighborhood 5   | |   Neighborhood 6   |
+|                    | |                    |  |                    | |                    |
++--------------------+ +--------------------+  +--------------------+ +--------------------+

package/art/fork-generation.bob

@@ -0,0 +1,13 @@
+                                                                validator action
+               +----+                                           ----------------
+         |     | L1 |                  E1
+         |     +----+            /             \                vote(E1)
+         |     | L2 |          E2                x
+         |     +----+        /    \           /     \           vote(E2)
+  time   |     | L3 |     E3        x        E3'      x
+         |     +----+    /  \     /   \     /  \     /  \       slash(E3)
+         |     | L4 |  x     x  E4     x   x    x   x    x
+         |     +----+  |     |  |      |   |    |   |    |      vote(E4)
+         v     | L5 |  xx   xx  xx    E5  xx   xx  xx   xx
+               +----+                                           hang on to E4 and E5 for more...
+

package/art/forks-pruned.bob

@@ -0,0 +1,9 @@
+     1
+     |
+     2
+    /|
+   / |
+  |  |
+  |  4
+  |
+  5

package/art/forks-pruned2.bob

@@ -0,0 +1,11 @@
+ 1
+ |
+ 3
+ |\
+ | \
+ |  |
+ |  |
+ |  |
+ 6  |
+    |
+    7

package/art/forks.bob

@@ -0,0 +1,13 @@
+     1
+     |\
+     2 \
+    /|  |
+   / |  3
+  |  |  |\
+  |  4  | \
+  |     |  |
+  5     |  |
+        |  |
+        6  |
+           |
+           7

package/art/passive-staking-callflow.msc

@@ -0,0 +1,30 @@
+msc {
+  hscale="2.2";
+   VoteSigner,
+   Validator,
+   Cluster,
+   StakerX,
+   StakerY;
+
+   |||;
+  Validator box Validator [label="boot.."];
+
+  VoteSigner <:> Validator [label="register\n\n(optional)"];
+  Validator => Cluster [label="VoteState::Initialize(VoteSigner)"];
+  StakerX => Cluster [label="StakeState::Delegate(Validator)"];
+  StakerY => Cluster [label="StakeState::Delegate(Validator)"];
+
+     |||;
+  Validator box Cluster [label="\nvalidate\n"];
+  Validator => VoteSigner [label="sign(vote)"];
+  VoteSigner >> Validator [label="signed vote"];
+
+  Validator => Cluster [label="gossip(vote)"];
+  ...;
+  ... ;
+  Validator abox Validator [label="\nmax\nlockout\n"];
+       |||;
+  Cluster box Cluster [label="credits redeemed (at epoch)"];
+
+
+}

package/art/retransmit_stage.bob

@@ -0,0 +1,45 @@
+                                                   +------------+
+                                                   |  Gossip    |
+                                                   |  Service   |
+                                                   |            |
+                                                   +------------+
+                                                          |ContactInfo
+                                                          |
+                          +------------------------------------------------------------------------+
+                          |                               |                                        |
+                          |  Retransmit Stage             |                                        |
+                          |                               |                                        |
+                          |  +--------------------------------------+                              |
+                          |  |Window Service              |         |                              |                      +---------+
+                          |  |                            |         |          +---------------+   |  +-----------+       |         |
+           Packets        |  | +----------------+         |         |  Shreds  |               |   |  | Deshredder|       | Replay  |
+          +------------------->+ ShredFilter    +----------------------------->+ Blockstore    +------| (entries) |------>+ Stage   |
+                          |  | +-----------+-+--+         |         |          |               |   |  +-----------+       |         |
++--------+                |  |        ^      |            |         |          |               |   |                      +---------+
+|        | Leader Schedule|  |        |      |            |         |          |               |   |
+| Bank   +----------------------------+      |     +------+----+    |          +-------+-------+   |
+|        |                |  |               |     | Repair    |    |                  |           |
++--------+    +----------------------------------->+ Service   |    | Incomplete       |           |
+              |           |  |               |     |           +<----------------------+           |
+              |           |  |               |     +-----------+    | Slots                        |
+              |           |  |               |                      |                              |
+              |           |  +--------------------------------------+                              |
+              |           |                  |Shreds                                               |
+              |           |                  v                                                     |
+              v           |          +-------+---------+                                           |
+     +--------+-----+     |          |                 |                                           |
+     |              |     |          | Retransmitter   |                                           |
+     | Peer         |     |          |                 |                                           |
+     | Validators   +<---------------+                 |                                           |
+     |              |     |          +--------+--------+                                           |
+     |              |     |                   ^                                                    |
+     +--------------+     |                   |                                                    |
+                          +------------------------------------------------------------------------+
+                                              |
+                                   ContactInfo|
+                                              |
+                                      +-------+-+
+                                      | Gossip  |
+                                      | Service |
+                                      |         |
+                                      +---------+

package/art/runtime.bob

@@ -0,0 +1,10 @@
+.------------.     .-----------.    .---------------.    .--------------.    .-----------------------.
+| PoH verify +---> | sigverify +--->| lock accounts +--->| validate fee +--->| allocate new accounts +--->
+|     TVU    |     `-----------`    `---------------`    `--------------`    `-----------------------`
+`------------`
+
+    .---------------.    .---------.    .------------.    .-----------------.   .-----------------.
+--->| load accounts +--->| execute +--->| PoH record +--->| commit accounts +-->| unlock accounts |
+    `---------------`    `---------`    |    TPU     |    `-----------------`   `-----------------`
+                                        `------------`
+

package/art/sdk-tools.bob

@@ -0,0 +1,20 @@
+
+                 .-------------------------------------.
+                 | Solana Runtime                      |
+                 |                                     |
+  .----------.   |   .------------.   .------------.   |
+  | Program  |   |   | BPF        |   | Executable |   |
+  | Author   +------>| Bytecode   +-->| Account    |   |
+  |          |   |   | Verifier   |   |            |   |
+  `----------`   |   `------------`   `------------`   |
+                 |                           |         |
+                 |          .----------------`         |
+                 |          |  LoadAccounts            |
+                 |          V                          |
+  .----------.   |   .------------.   .-------------.  |
+  |          |   |   |  BPF       |   | BPF         |  |
+  |  Client  +------>|  Loader    +-->| Interpreter |  |
+  |          |   |   |            |   |             |  |
+  `----------`   |   `------------`   `-------------`  |
+                 |                                     |
+                 `-------------------------------------`

package/art/spv-bank-hash.bob

@@ -0,0 +1,19 @@
+                                   +----------+
+                                   | Bank-Hash|
+                                   +----------+
+                                        ^
+                                        |
+                  +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
+                  :                                              :
+                  :       +--------------+     +-------------+   :
+                  : Hash( | Accounts-Hash|  +  | Block-Merkle| ) :
+                  :       +--------------+     +-------------+   :
+                  :              ^                               :
+                  +~~~~~~~~~~~~~ | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
+                                 |
+ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+ 
+ :       +---------------+   +---------------+          +---------------+   : 
+ : Hash( | Hash(Account1)| + | Hash(Account2)| +  ... + | Hash(AccountN)| ) : 
+ :       +---------------+   +---------------+          +---------------+   : 
+ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+ 
+

package/art/spv-block-merkle.bob

@@ -0,0 +1,19 @@
+                                   +---------------+
+                                   |  Block-Merkle |
+                                   +---------------+
+                                  ^                ^
+                                 /                  \
+                      +-------------+            +-------------+
+                      | Entry-Merkle|            | Entry-Merkle|
+                      +-------------+            +-------------+
+                         ^                                 ^
+                        /                                   \
+                  +-------+                               +-------+
+                  |  Hash |                               |  Hash |
+                  +-------+                               +-------+
+                 ^        ^                                ^      ^
+                /         |                                |       \
+ +-----------------+   +-----------------+   +-----------------+   +---+
+ | Hash(T1, status)|   | Hash(T2, status)|   | Hash(T3, status)|   | 0 | 
+ +-----------------+   +-----------------+   +-----------------+   +---+
+

package/art/tpu.bob

@@ -0,0 +1,19 @@
+
+                                        .-------------.
+                                        | PoH Service |
+                                        `--------+----`
+                                            ^    |
+             .------------------------------|----|--------------------.
+             | TPU                          |    v                    |
+             |  .-------.  .-----------.  .-+-------.  .-----------.  |  .------------.
+ .---------. |  | Fetch |  | SigVerify |  | Banking |  | Broadcast |  |  | Downstream |
+ | Clients |--->| Stage |->| Stage     |->| Stage   |->| Stage     |---->| Validators |
+ `---------` |  |       |  |           |  |         |  |           |  |  |            |
+             |  `-------`  `-----------`  `----+----`  `-----------`  |  `------------`
+             |                                 |                      |
+             `---------------------------------|----------------------`
+                                               |
+                                               v
+                                            .------.
+                                            | Bank |
+                                            `------`

package/art/tvu.bob

@@ -0,0 +1,37 @@
+                                                                         +------------+
+                                                                         |   Gossip   |
+                                                                         |   Service  |
+                                 +-------------+                         |            |
+                                 |Child        |    +------------+       +-+-----+----+
+                                 |Validators   |    |Neighborhood|         |     ^
+                                 |             |    |Validators  |         |     |
+                                 +-------+-----+    |            |         |     |
+                                         ^          +---------+--+     Peer|     |Votes
+                                         |                    ^        List|     |
+                                         +-----------------+  |            |     |
+                                       shreds(forward=true)|  |            |     |
+                         +-----------------------------------------------------------------------------------------+
+                         |                                 |  |            |     |                                 |
+                         |  TVU                            |  |   +--------+     |                                 |
+                         |                                 |  |   v              |                                 |
++------------+           |  +-------+  +------------+    +-+--+---+---+      +---+--------------+      +---------+ |
+|            |    Repair |  |       |  |            |    | Retransmit |      | Replay           |      | Storage | |
+| Upstream   +------------->+       +->+ Shred      +--->+ Stage      +----->+ Stage            +----->+ Stage   | |
+| Validators |     TVU   |  | Shred |  | Verify     |    |            |      | +--------------+ |      |         | |
+|            +------------->+ Fetch |  | Leader Sig |    +------+-----+      | | PoH Verify   | |      +---------+ |
+|            |           |  | Stage |  | Stage      |           ^            | | TX Sig Verify| |                  |
+|            +------------->+       |  |            |           |            | |              | |                  |
+|            |   TVU     |  |       |  +--+---------+           |            | +-+------------+ |                  |
++------------+   Forwards|  +-------+     ^                     |            |   |              |                  |
+                         |                |                     |            +------------------+                  |
+                         |                |                     |                |                                 |
+                         |                |                     |                |                                 |
+                         |                |                     |                |                                 |
+                         +-----------------------------------------------------------------------------------------+
+                                          |                     |                |
+                                          |                     |Validator       v
+                                          |                     |Stakes      +---+-----+
+                                          |                     +------------+         |
+                                          +----------------------------------+ Bank    |
+                                                Leader                       |         |
+                                                Schedule                     +---------+

package/art/validator-proposal.bob

@@ -0,0 +1,60 @@
+
+                                 .------------.
+                                 | Upstream   |
+                                 | Validators |
+                                 `----+-------`
+                                      |
+                                      |
+             .-----------------------------------.
+             | Validator              |          |
+             |                        v          |
+             |  .-----------.    .------------.  |
+ .--------.  |  | Fetch     |    | Repair     |  |
+ | Client +---->| Stage     |    | Stage      |  |
+ `--------`  |  `---+-------`    `----+-------`  |
+             |      |                 |          |
+             |      v                 v          |
+             |  .-----------.    .------------.  |
+             |  | TPU       |<-->| Blockstore |  |
+             |  |           |    |            |  |
+             |  `-----------`    `----+-------`  |
+             |                        |          |
+             |                        v          |
+             |                   .------------.  |
+             |                   | Multicast  |  |
+             |                   | Stage      |  |
+             |                   `----+-------`  |
+             |                        |          |
+             `-----------------------------------`
+                                      |
+                                      v
+                                 .------------.
+                                 | Downstream |
+                                 | Validators |
+                                 `------------`
+
+
+
+                                 .------------.
+                                 | PoH        |
+                                 | Service    |
+                                 `-------+----`
+                                     ^   |
+                                     |   |
+             .-----------------------------------.
+             | TPU                   |   |       |
+             |                       |   v       |
+  .-------.  |  .-----------.    .---+--------.  |  .------------.
+  | Fetch +---->| SigVerify +--->| Banking    |<--->| Blockstore |
+  | Stage |  |  | Stage     |    | Stage      |  |  |            |
+  `-------`  |  `-----------`    `-----+------`  |  `------------`
+             |                         |         |
+             |                         |         |
+             `-----------------------------------`
+                                       |
+                                       v
+                                 .------------.
+                                 | Banktree   |
+                                 |            |
+                                 `------------`
+

package/art/validator.bob

@@ -0,0 +1,30 @@
+             .---------------------------------------.
+             |  Validator                            |
+             |                                       |
+ .--------.  |  .-------------------.                |
+ |        |---->|                   |                |
+ | Client |  |  | JSON RPC Service  |                |
+ |        |<----|                   |                |
+ `----+---`  |  `-------------------`                |
+      |      |     ^                                 |
+      |      |     |     .----------------.          | .------------------.
+      |      |     |     | Gossip Service |<-----------| Validators       |
+      |      |     |     `----------------`          | |                  |
+      |      |     |           ^                     | |                  |
+      |      |     |           |                     | |  .------------.  |
+      |      | .---+---.  .----+---. .------------.  | |  |            |  |
+      |      | | Bank  |<-+ Replay | | ShredFetch |<------+ Upstream   |  |
+      |      | | Forks |  | Stage  | |  Stage     |  | |  | Validators |  |
+      |      | `-------`  `--------` `--+---------`  | |  |            |  |
+      |      |     ^              ^     |            | |  `------------`  |
+      |      |     |              |     v            | |                  |
+      |      |     |           .--+---------.        | |                  |
+      |      |     |           | Blockstore |        | |                  |
+      |      |     |           `------------`        | |  .------------.  |
+      |      |     |                ^                | |  |            |  |
+      |      |     |                |                | |  | Downstream |  |
+      |      |  .--+--.     .-------+---.            | |  | Validators |  |
+      `-------->| TPU +---->| Broadcast +---------------->|            |  |
+             |  `-----`     | Stage     |            | |  `------------`  |
+             |              `-----------`            | `------------------`
+             `---------------------------------------`

package/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve("@docusaurus/core/lib/babel/preset")],
+};

package/build-cli-usage.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+set -e
+
+cd "$(dirname "$0")"
+cargo=../cargo
+
+# shellcheck source=ci/rust-version.sh
+source ../ci/rust-version.sh stable
+
+: "${rust_stable:=}" # Pacify shellcheck
+
+usage=$("$cargo" stable -q run -p solana-cli -- -C ~/.foo --help | sed -e 's|'"$HOME"'|~|g' -e 's/[[:space:]]\+$//')
+
+out=${1:-src/cli/usage.md}
+
+cat src/cli/.usage.md.header > "$out"
+
+section() {
+  declare mark=${2:-"###"}
+  declare section=$1
+  read -r name rest <<<"$section"
+
+  printf '%s %s
+' "$mark" "$name"
+  printf '```text
+%s
+```
+
+' "$section"
+}
+
+section "$usage" >> "$out"
+
+usage=$(sed -e '/^ \{5,\}/d' <<<"$usage")
+
+in_subcommands=0
+while read -r subcommand rest; do
+  [[ $subcommand == "SUBCOMMANDS:" ]] && in_subcommands=1 && continue
+  if ((in_subcommands)); then
+      section "$("$cargo" stable -q run -p solana-cli -- help "$subcommand" | sed -e 's|'"$HOME"'|~|g' -e 's/[[:space:]]\+$//')" "####" >> "$out"
+  fi
+done <<<"$usage">>"$out"

package/build.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+set -ex
+
+cd "$(dirname "$0")"
+
+# shellcheck source=ci/env.sh
+source ../ci/env.sh
+
+: "${rust_stable_docker_image:=}" # Pacify shellcheck
+
+# shellcheck source=ci/rust-version.sh
+source ../ci/rust-version.sh
+../ci/docker-run.sh "$rust_stable_docker_image" docs/build-cli-usage.sh
+../ci/docker-run.sh "$rust_stable_docker_image" docs/convert-ascii-to-svg.sh
+./set-solana-release-tag.sh
+
+# Get current channel
+eval "$(../ci/channel-info.sh)"
+
+# Synchronize translations with Crowdin only on stable channel
+if [ "$CHANNEL" = stable ]; then
+  echo "Downloading & updating translations..."
+  npm run crowdin:download
+  npm run crowdin:upload
+fi
+
+# Build from /src into /build
+npm run build
+echo $?
+
+# Publish only from merge commits and beta release tags
+if [[ -n $CI ]]; then
+  if [[ -z $CI_PULL_REQUEST ]]; then
+    if [[ -n $CI_TAG ]] && [[ $CI_TAG != $BETA_CHANNEL* ]]; then
+      echo "not a beta tag"
+      exit 0
+    fi
+    ./publish-docs.sh
+  fi
+fi