[docs] update tangle and dkg documentation (#85)

* update tangle docs * yarn format * update desp * update dark images * Update pages/docs/protocols/dkg/authority-selection.mdx Co-authored-by: Dustin Brickwood <dustinbrickwood204@gmail.com> * Update pages/docs/protocols/dkg/key-rotation.mdx Co-authored-by: Dustin Brickwood <dustinbrickwood204@gmail.com> * Update pages/docs/tangle-network/node-operators/deploy-with-docker/collator-node.mdx Co-authored-by: Dustin Brickwood <dustinbrickwood204@gmail.com> * update review fixes * Update pages/docs/tangle-network/node-operators/systemd/collator-node.mdx Co-authored-by: Dustin Brickwood <dustinbrickwood204@gmail.com> * Update pages/docs/tangle-network/node-operators/deploy-with-docker/collator-node.mdx Co-authored-by: Dustin Brickwood <dustinbrickwood204@gmail.com> * update review suggesstions * update review suggesstion --------- Co-authored-by: Dustin Brickwood <dustinbrickwood204@gmail.com>
tangle-network · Mar 22, 2023 · 583daea · 583daea
1 parent 51da7bf
commit 583daea
Show file tree

Hide file tree

Showing 21 changed files with 671 additions and 54 deletions.
diff --git a/components/UseCasesTangle.tsx b/components/UseCasesTangle.tsx
@@ -97,6 +97,14 @@ export const TestNetworkArea = () => {
         }}
         href="https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Ftangle-standalone1.webb.tools%2F#/explorer"
       ></DetailedFeatureLink>
+      <DetailedFeatureLink
+        feature={{
+          Icon: ServerIcon,
+          description: `Tangle Parachain testnet runs on a testnet relaychain hosted by Webb.`,
+          name: "Tangle Parachain Network",
+        }}
+        href="https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Ftangle1.webb.tools%2F#/explorer"
+      ></DetailedFeatureLink>
     </div>
   );
 };
diff --git a/components/images/DKGReputation.tsx b/components/images/DKGReputation.tsx
@@ -0,0 +1,16 @@
+import Image from "next/image";
+import DKGReputationLight from "./dkg_reputation_calculcation_light.png";
+import DKGReputationDark from "./dkg_reputation_calculcation_dark.png";
+
+export default function DkgReputationImages(props) {
+  return (
+    <>
+      <div className="block dark:hidden">
+        <Image src={DKGReputationLight} alt="Dkg Reputation light" />
+      </div>
+      <div className="hidden dark:block">
+        <Image src={DKGReputationDark} alt="Dkg Reputation dark" />
+      </div>
+    </>
+  );
+}
diff --git a/components/images/DKGRotation.tsx b/components/images/DKGRotation.tsx
@@ -0,0 +1,16 @@
+import Image from "next/image";
+import DKGRotationLight from "./dkg_rotation_light.png";
+import DKGRotationDark from "./dkg_rotation_dark.png";
+
+export default function DKGRotationImages(props) {
+  return (
+    <>
+      <div className="block dark:hidden">
+        <Image src={DKGRotationLight} alt="Dkg Rotation light" />
+      </div>
+      <div className="hidden dark:block">
+        <Image src={DKGRotationDark} alt="Dkg Rotation dark" />
+      </div>
+    </>
+  );
+}
diff --git a/components/images/dkg_reputation_calculcation_dark.png b/components/images/dkg_reputation_calculcation_dark.png
diff --git a/components/images/dkg_reputation_calculcation_light.png b/components/images/dkg_reputation_calculcation_light.png
diff --git a/components/images/dkg_rotation_dark.png b/components/images/dkg_rotation_dark.png
diff --git a/components/images/dkg_rotation_light.png b/components/images/dkg_rotation_light.png
diff --git a/pages/docs/protocols/dkg/authority-selection.mdx b/pages/docs/protocols/dkg/authority-selection.mdx
@@ -1,8 +1,10 @@
 ---
 title: Authority Selection
-description: Only build the workspaces you care about
+description: Authority Selection logic for DKG
 ---
 
+import DKGReputationImages from '../../../../components/images/DKGReputation'
+
 # Authority Selection
 
 The authority selection system for DKG authorities uses a simple reputation mechanism for selecting the best set
@@ -13,3 +15,21 @@ participate in either protocols.
 For a keygen threshold of **_n_** and a signing threshold of **_t_**, we take the top-**_n_** authorities on chain by
 reputation. Out of these **_n_** keygen authorities, **_t+1_** of them are selected for signing. The keygen set remains
 fixed over the course of the session, whereas the signing set can change amidst misbehaviours in signing protocol participation.
+
+# Reputation Calculation
+
+The `pallet-dkg-metadata` is responsible for calculating and maintaining the reputation scores of all active validators. Reputation serves as a metric to assess and evaluate the authorities, taking into account the number of valid keygen operations performed by the authority and any reported misbehaviors.
+
+The misbehaviour reporting process is based on an honest-threshold assumption. If DKG authorities misbehave off-chain, any observing authority can submit a report against the offending authority. Once a threshold number of reports are submitted, the offending authority will experience a loss of reputation. The reputation map is used by each DKG authority to ensure that every authority can generate a deterministic signing set for threshold signing protocols. Initially, the signing set consists of the top `t` DKG authorities according to their reputation.
+
+The formula for updating reputation based on misbehaviour is as follows:
+
+```
+AUTHORITY_REPUTATION = DECAY_PERCENTAGE * AUTHORITY_REPUTATION
+```
+
+# Jailing authorities
+
+For each instance of misconduct that is verified and reported to an authority, the implicated authority will be temporarily suspended or "jailed" for a specific number of sessions. During this suspension, the authority will not be included in the selection process for the authority selection set. This serves as a punitive measure against malicious behaviour. The authority may be reinstated after a predetermined period of time has passed.
+
+<DKGReputationImages />
diff --git a/pages/docs/protocols/dkg/governance/pallets.mdx b/pages/docs/protocols/dkg/governance/pallets.mdx
@@ -1,6 +1,6 @@
 ---
 title: Governance
-description: Only build the workspaces you care about
+description: Governance modules for tangle network
 ---
 
 # DKG Governance

diff --git a/pages/docs/protocols/dkg/key-rotation.mdx b/pages/docs/protocols/dkg/key-rotation.mdx
@@ -1,8 +1,10 @@
 ---
 title: Key rotation
-description: Only build the workspaces you care about
+description: DKG Key rotation logic
 ---
 
+import DKGRotationImages from '../../../../components/images/DKGRotation'
+
 # Key rotation
 
 The DKG required network participants to rotate their shared private signing keys in an effort to keep the
@@ -17,3 +19,9 @@ next authorities are selected.
 4. Once this signature is posted, anyone can propagate it.
    - Any relayer.
    - Any user who wants to update the governor of their contract.
+
+# Key rotation flow
+
+The on-chain keys are rotate every session, this is done so that the DKG validators and network validators are aligned. At the end of the session, the `dkg-gadget` triggers the process to generate a new key. The new key is generated by the new on-chain authorities, these authorities then work together to generate a new key and signature.
+
+<DKGRotationImages />
diff --git a/pages/docs/protocols/dkg/misbehaviour.mdx b/pages/docs/protocols/dkg/misbehaviour.mdx
@@ -1,6 +1,6 @@
 ---
 title: Misbehaviour Reporting & Reputation
-description: Only build the workspaces you care about
+description: DKG Authorities misbehaviour reporting
 ---
 
 # Misbehaviour Reporting & Reputation

diff --git a/pages/docs/tangle-network/node-operators/deploy-with-docker/_meta.json b/pages/docs/tangle-network/node-operators/deploy-with-docker/_meta.json
@@ -1,5 +1,6 @@
 {
   "full-node": "Full Node",
   "collator-node": "Collator Node",
+  "validator-node": "Validator Node",
   "relayer-node": "Collator Node with Relayer"
 }
diff --git a/pages/docs/tangle-network/node-operators/deploy-with-docker/collator-node.mdx b/pages/docs/tangle-network/node-operators/deploy-with-docker/collator-node.mdx
@@ -0,0 +1,255 @@
+---
+title: Deploying with Docker
+description: Deploy a Tangle validator node with only a few steps.
+---
+
+import Callout from "../../../../../components/Callout";
+
+# Deploying with Docker
+
+A Tangle node can be spun up quickly using Docker. For more information on installing Docker,
+please visit the official Docker [docs](https://docs.docker.com/get-docker/). When connecting to Tangle on Kusama, it will take a few days to completely sync the embedded relay chain. Make sure that your system meets the requirements which can read [here](/docs/tangle-network/node-operators/requirements)
+
+## Parachain Testnet
+
+### **1. Pull the Tangle Docker image:**
+
+Although we can make use of the provided `docker-compose` file in the [Tangle repo](https://github.com/webb-tools/tangle/tree/main/docker/tangle-parachain), we pull the `tangle-parachain:main` Docker image from ghcr.io
+so that we can generate and insert our required keys before starting the node.
+
+```
+# Only use "main" if you know what you are doing, it will use the latest and maybe unstable version of the node.
+
+docker pull ghcr.io/webb-tools/tangle/tangle-parachain:main
+```
+
+### **2. Create a local directory to store the chain data:**
+
+Let us create a directory where we will store all the data for our node. This includes the chain data, keys, and logs.
+
+```
+mkdir /var/lib/tangle/
+```
+
+### **3. Fetch applicable chainspec(s):**
+
+To join the Tangle Test network as collator we need to fetch the appropriate chainspec for the Tangle network.
+Download the latest chainspec for parachain testnet:
+
+```
+# Fetches chainspec for Tangle network
+wget https://github.com/webb-tools/tangle/blob/main/chainspecs/testnet/tangle-parachain.json
+```
+
+Please make a reference where you have stored this `json` file as we will need it in the next steps.
+
+### **4. Generate and store keys:**
+
+We need to generate the required keys for our node. For more information on these keys, please see the [Required Keys](https://docs.webb.tools/docs/tangle-network/node-operators/required-keys/) section.
+The keys we need to generate include the following:
+
+- DKG key (Ecdsa)
+- Aura key (Sr25519)
+- Account key (Sr25519)
+- Nimbus key (Sr25519)
+- Rand key (Sr25519)
+- ImOnline key (Sr25519)
+
+Let's now insert our required secret keys, we will not pass the SURI in the command, instead it will be interactive, where you
+should paste your SURI when the command asks for it.
+
+**Account Keys**
+
+```
+# it will ask for your suri, enter it.
+docker run --rm -it --platform linux/amd64 --network="host" -v "/var/lib/data" \
+ghcr.io/webb-tools/tangle/tangle-parachain:main \
+     key insert --base-path /var/lib/tangle/ \
+    --chain /data/chainspecs/tangle-parachain.json \
+    --scheme Sr25519 \
+    --key-type acco
+```
+
+**Aura Keys**
+
+```
+docker run --rm -it --platform linux/amd64 --network="host" -v "/var/lib/data" \
+ghcr.io/webb-tools/tangle/tangle-parachain:main \
+    key insert --base-path /var/lib/tangle/ \
+    --chain /data/chainspecs/tangle-parachain.json \
+    --scheme Sr25519 \
+    --key-type aura
+```
+
+**Im-online Keys** - **these keys are optional (required if you are running as a collator)**
+
+```
+docker run --rm -it --platform linux/amd64 --network="host" -v "/var/lib/data" \
+ghcr.io/webb-tools/tangle/tangle-parachain:main \
+    key insert --base-path /var/lib/tangle/ \
+    --chain /data/chainspecs/tangle-parachain.json \
+    --scheme Sr25519 \
+    --key-type imon
+```
+
+**DKG Keys**
+
+```
+docker run --rm -it --platform linux/amd64 --network="host" -v "/var/lib/data" \
+ghcr.io/webb-tools/tangle/tangle-parachain:main \
+    tangle-parachain key insert --base-path /data \
+    --chain /data/chainspecs/tangle-parachain.json \
+    --scheme Ecdsa \
+    --key-type wdkg
+```
+
+**Nimbus Keys**
+
+```
+docker run --rm -it --platform linux/amd64 --network="host" -v "/var/lib/data" \
+ghcr.io/webb-tools/tangle/tangle-parachain:main \
+    tangle-parachain key insert --base-path /data \
+    --chain /data/chainspecs/tangle-parachain.json \
+    --scheme Sr25519 \
+    --key-type nmbs
+```
+
+**Rand Keys**
+
+```
+docker run --rm -it --platform linux/amd64 --network="host" -v "/var/lib/data" \
+ghcr.io/webb-tools/tangle/tangle-parachain:main \
+    tangle-parachain key insert --base-path /data \
+    --chain /data/chainspecs/tangle-parachain.json \
+    --scheme Sr25519 \
+    --key-type rand
+```
+
+To ensure you have successfully generated the keys correctly run:
+
+```
+ls ~/webb/tangle/chains/*/keystore
+# You should see a some file(s) there, these are the keys.
+```
+
+### **5. Start Tangle Collator node:**
+
+To start the node run the following command:
+
+```
+docker run --platform linux/amd64 --network="host" -v "/var/lib/data" --entrypoint ./tangle-parachain \
+ghcr.io/webb-tools/tangle/tangle-parachain:main \
+--base-path=/data \
+--chain dev \
+--name="YOUR-NODE-NAME" \
+--execution wasm \
+--wasm-execution compiled \
+--trie-cache-size 0 \
+-- \
+--execution wasm \
+--name="YOUR-NODE-NAME (Embedded Relay)"
+```
+
+<Callout type="info">
+  For an overview of the above flags, please refer to the [CLI Usage](https://docs.webb.tools/docs/tangle-network/node-operators/api-reference/cli/) page of our documentation.
+</Callout>
+
+Once Docker pulls the necessary images, your Tangle node will start, displaying lots of information,
+such as the chain specification, node name, role, genesis state, and more.
+
+```
+2023-03-22 14:55:51 Tangle Parachain
+2023-03-22 14:55:51 ✌️  version 0.1.15-54624e3-aarch64-macos
+2023-03-22 14:55:51 ❤️  by Webb Technologies Inc., 2017-2023
+2023-03-22 14:55:51 📋 Chain specification: Tangle Testnet
+2023-03-22 14:55:51 🏷  Node name: cooing-morning-2891
+2023-03-22 14:55:51 👤 Role: FULL
+2023-03-22 14:55:51 💾 Database: RocksDb at /Users/local/Library/Application Support/tangle-parachain/chains/local_testnet/db/full
+2023-03-22 14:55:51 ⛓  Native runtime: tangle-parachain-115 (tangle-parachain-1.tx1.au1)
+2023-03-22 14:55:51 Bn254 x5 w3 params
+2023-03-22 14:55:51 Verifier params for mixer
+2023-03-22 14:55:51 Verifier params for vanchor
+2023-03-22 14:55:51 [0] 💸 generated 5 npos voters, 5 from validators and 0 nominators
+2023-03-22 14:55:51 [0] 💸 generated 5 npos targets
+2023-03-22 14:55:51 [0] 💸 generated 5 npos voters, 5 from validators and 0 nominators
+2023-03-22 14:55:51 [0] 💸 generated 5 npos targets
+2023-03-22 14:55:51 [0] 💸 new validator set of size 5 has been processed for era 1
+2023-03-22 14:55:52 🔨 Initializing Genesis block/state (state: 0xfd16…aefd, header-hash: 0x7c05…a27d)
+2023-03-22 14:55:52 👴 Loading GRANDPA authority set from genesis on what appears to be first startup.
+2023-03-22 14:55:53 Using default protocol ID "sup" because none is configured in the chain specs
+2023-03-22 14:55:53 🏷  Local node identity is: 12D3KooWDaeXbqokqvEMqpJsKBvjt9BUz41uP9tzRkYuky1Wat7Z
+2023-03-22 14:55:53 💻 Operating system: macos
+2023-03-22 14:55:53 💻 CPU architecture: aarch64
+2023-03-22 14:55:53 📦 Highest known block at #0
+2023-03-22 14:55:53 〽️ Prometheus exporter started at 127.0.0.1:9615
+2023-03-22 14:55:53 Running JSON-RPC HTTP server: addr=127.0.0.1:9933, allowed origins=["http://localhost:*", "http://127.0.0.1:*", "https://localhost:*", "https://127.0.0.1:*", "https://polkadot.js.org"]
+2023-03-22 14:55:53 Running JSON-RPC WS server: addr=127.0.0.1:9944, allowed origins=["http://localhost:*", "http://127.0.0.1:*", "https://localhost:*", "https://127.0.0.1:*", "https://polkadot.js.org"]
+```
+
+If you followed the installation instructions for Tangle, once synced, you will be connected to peers and see
+blocks being produced on the Tangle network! Note that in this case you need to also sync to the Polkadot/Kusama
+relay chain, which might take a few days.
+
+### Run via Docker Compose
+
+The docker-compose file will spin up a container running tangle parachain node, but you have to set the following environment variables. Remember to customize your the values depending on your environment and then copy paste this to CLI.
+
+```
+RELEASE_VERSION=main
+CHAINSPEC_PATH=/tmp/chainspec/
+```
+
+After that run:
+
+```
+docker compose up -d
+```
+
+## Update the Client
+
+As Tangle development continues, it will sometimes be necessary to upgrade your node software. Node operators will be notified
+on our Discord channel when upgrades are available and whether they are necessary (some client upgrades are optional).
+The upgrade process is straightforward and is the same for a full node or collator.
+
+1. Stop the docker container:
+
+```
+sudo docker stop `CONTAINER_ID`
+```
+
+2. Get the latest version of Tangle from the Tangle GitHub Release [page](https://github.com/webb-tools/tangle/pkgs/container/tangle%2Ftangle-parachain)
+
+3. Pull the latest version of Tangle binary by doing `docker pull ghcr.io/webb-tools/tangle/tangle-parachain:{VERSION_CODE}`.
+   Example, if the latest version of Tangle is v0.1.2, then the command would be `docker pull ghcr.io/webb-tools/tangle/tangle-parachain:v0.1.12`
+
+4. Restart the tangle container and you should have the updated version of the client.
+
+## Purge Your Node
+
+If you need a fresh instance of your Tangle node, you can purge your node by removing the associated data directory.
+
+You'll first need to stop the Docker container:
+
+```
+sudo docker stop `CONTAINER_ID`
+```
+
+If you did not use the -v flag to specify a local directory for storing your chain data when you spun up your node, then the data folder is related
+to the Docker container itself. Therefore, removing the Docker container will remove the chain data.
+
+If you did spin up your node with the -v flag, you will need to purge the specified directory. For example, for the suggested data directly,
+you can run the following command to purge your parachain node data:
+
+```
+# purges parachain data
+sudo rm -rf /data/chains/*
+```
+
+If you ran with parachain node you can run the following command to purge your relay-chain node data:
+
+```
+# purges relay chain data
+sudo rm -rf /data/polkadot/*
+```
+
+Now that your chain data has been purged, you can start a new node with a fresh data directory!