From 1537529a82f7f1753142c4a44f5fbbdcc2542e1e Mon Sep 17 00:00:00 2001 From: Felix Nicolae Bucsa Date: Tue, 19 Sep 2023 13:05:59 +0100 Subject: [PATCH 01/26] feat(docs): add ledger docs --- pages/concepts.mdx | 38 +++++++++++++ pages/concepts/_meta.json | 3 +- pages/concepts/agents/_meta.json | 2 +- pages/concepts/ledger/_meta.json | 5 ++ pages/concepts/ledger/block-explorer.mdx | 27 ++++++++++ pages/concepts/ledger/intro.mdx | 19 +++++++ pages/concepts/ledger/validators.mdx | 39 ++++++++++++++ pages/guides.mdx | 32 +++++++++++ pages/guides/_meta.json | 1 + pages/guides/ledger/_meta.json | 11 ++++ pages/guides/ledger/cli/_meta.json | 8 +++ pages/references.mdx | 41 ++++++++++++++ pages/references/_meta.json | 3 +- pages/references/ledger/_meta.json | 6 +++ pages/references/ledger/active-networks.mdx | 51 ++++++++++++++++++ pages/references/ledger/mainnet-archive.mdx | 59 +++++++++++++++++++++ pages/references/ledger/security.mdx | 39 ++++++++++++++ pages/references/ledger/versions.mdx | 19 +++++++ 18 files changed, 400 insertions(+), 3 deletions(-) create mode 100644 pages/concepts/ledger/_meta.json create mode 100644 pages/concepts/ledger/block-explorer.mdx create mode 100644 pages/concepts/ledger/intro.mdx create mode 100644 pages/concepts/ledger/validators.mdx create mode 100644 pages/guides/ledger/_meta.json create mode 100644 pages/guides/ledger/cli/_meta.json create mode 100644 pages/references/ledger/_meta.json create mode 100644 pages/references/ledger/active-networks.mdx create mode 100644 pages/references/ledger/mainnet-archive.mdx create mode 100644 pages/references/ledger/security.mdx create mode 100644 pages/references/ledger/versions.mdx diff --git a/pages/concepts.mdx b/pages/concepts.mdx index 18da61c0e..5a8797e23 100644 --- a/pages/concepts.mdx +++ b/pages/concepts.mdx @@ -122,4 +122,42 @@ import { GuideBox } from "../components/feature-guide-tabs"; +## Ledger + +
+ Explore the topics you need to know in order to prepare for and develop on the Fetch network. +
+ + + + + + + + + + + + + + +
diff --git a/pages/concepts/_meta.json b/pages/concepts/_meta.json index a213476d0..ae0f34b41 100644 --- a/pages/concepts/_meta.json +++ b/pages/concepts/_meta.json @@ -1,5 +1,6 @@ { "agents": "uAgents", "agent-services": "Agentverse Services", - "ai-engine": "AI Engine" + "ai-engine": "AI Engine", + "ledger": "Ledger" } diff --git a/pages/concepts/agents/_meta.json b/pages/concepts/agents/_meta.json index 8fbe8d6b4..892f23ac1 100644 --- a/pages/concepts/agents/_meta.json +++ b/pages/concepts/agents/_meta.json @@ -1,4 +1,4 @@ { - "agents": "Introduction", + "agents": "Introduction \uD83D\uDE80", "rationale": "Why uAgents" } diff --git a/pages/concepts/ledger/_meta.json b/pages/concepts/ledger/_meta.json new file mode 100644 index 000000000..c2717293e --- /dev/null +++ b/pages/concepts/ledger/_meta.json @@ -0,0 +1,5 @@ +{ + "intro": "Introduction \uD83D\uDE80", + "block-explorer": "Block explorers \uD83D\uDD0E", + "validators": "Validators" +} diff --git a/pages/concepts/ledger/block-explorer.mdx b/pages/concepts/ledger/block-explorer.mdx new file mode 100644 index 000000000..730fc8e07 --- /dev/null +++ b/pages/concepts/ledger/block-explorer.mdx @@ -0,0 +1,27 @@ +import { Callout } from 'nextra/components' + +# Block explorer 🔎 + +Each of the available [networks ↗️](/concepts/ledger/active-networks) has a dedicated block explorer website associated with it. This is a useful tool for monitoring network activity. + +## Logging in with the ledger nano + +Return to the block explorer landing page and click on the key button in the top right corner. Here, you will be prompted to _Sign in With Ledger_. **You must accept this request on your ledger nano device**. After completing this process, the key button will be replaced by a person icon with a link to your personal address page, which keeps track of the activity that you have performed on the test-net. + +## Getting testnet tokens from the faucet + +For networks that support it, you can obtain tokens for your account by copying the address and pasting it into the token faucet. Then, return to the main page, press the **Get Funds** button and paste your address in the pop-up. Afterwards, you can return to your address page (via the person icon) and should observe that you have been allocated **1 TESTFET**. + +## Transferring tokens to another address + +After receiving tokens, you can send these to another address using the purple **Transfer** button on your address page. This will trigger a pop-up that prompts you to specify the destination address and the amount you wish to transfer. After filling in this information, you will be asked to sign the transaction using your ledger nano. The confirmation that the transaction has been broadcast gives two links that can be used to check that the transaction has been executed on the blockchain using either the transaction hash or your account page. + + + The transaction format includes a memo field that can be used to check the transaction information on the ledger nano display. + + +## Delegating stake to a validator + +You can delegate your test-net tokens to a validator who is operating the network by clicking on the **Validators** tab, and selecting one of the validators that you wish to delegate stake towards. In the **Voting Power** panel there is an option to **DELEGATE** tokens. Pressing this button will trigger a pop-up that prompts you to select a delegation amount and then sign the transaction with your Ledger Nano device. + +Upon delegating tokens, buttons labeled **REDELEGATE** and **UNDELEGATE** will appear. Delegating tokens to a validator rewards you for helping to secure the network. If you wish to delegate to a different validator, you can do so through a **REDELEGATE** transaction. You can retrieve any bonded tokens to your address by submitting an **UNDELEGATE** request, which will return the tokens after a 21-day waiting period. The rewards you receive from delegating tokens to a validator are displayed on your account page and can be sent to your address through a **WITHDRAW** transaction. diff --git a/pages/concepts/ledger/intro.mdx b/pages/concepts/ledger/intro.mdx new file mode 100644 index 000000000..63ac2adba --- /dev/null +++ b/pages/concepts/ledger/intro.mdx @@ -0,0 +1,19 @@ +import { Callout } from 'nextra/components' + +# Ledger + +## Mainnet is here! + +The fetchhub mainnet forms the core of the Fetch.ai ecosystem. In these pages, you will find all information to setup your client and connect on the [network](/concepts/ledger/active-networks) and [cli-introduction](/concepts/ledger/mainnet-archive) pages. + +This documentation covers some of the things you need to know in order to prepare for and develop on this network. + +## Test Networks + +The starting point for most will be [our test network](/concepts/ledger/active-networks#test-nets), since it can provide you with test tokens with no value, that you can safely experiment with. + +Head over the [Command line client](https://docs.fetch.ai/ledger_v2/cli-introduction/) section for guidance on how to install and configure the `fetchd` client. + + + This documentation is currently under construction, and the content may not be up-to-date. + diff --git a/pages/concepts/ledger/validators.mdx b/pages/concepts/ledger/validators.mdx new file mode 100644 index 000000000..bbe9b8a8f --- /dev/null +++ b/pages/concepts/ledger/validators.mdx @@ -0,0 +1,39 @@ +# Validators + +## Overview + +The Fetch.ai Ledger relies on a set of validators that are responsible for committing new blocks in the blockchain. These validators participate in the consensus protocol by broadcasting votes which contain cryptographic signatures signed by each validator's private key. + +Validator candidates can bond their own FET and have FET delegated, or staked, to them by token holders. The validators are determined by who has the most stake delegated to them. The top N validator candidates with the most stake will become the active validators. + +Validators and their delegators will earn FET as block provisions and tokens as transaction fees through execution of the consensus protocol. Transaction fees will be paid in FET. + +If validators double sign, are frequently offline or do not participate in governance, their staked FET (including FET of users that delegated to them) can be slashed. The penalty depends on the severity of the violation. + +## Hardware requirements + +The hardware resources for running a validator node largely depend on the network load. As a recommended configuration we suggest the following requirements: + + - 2 x CPU, either Intel or AMD, with the SSE4.1, SSE4.2 and AVX flags (use lscpu to verify). + - 8 GB RAM. + - 500 GB SSD. + - 100 Mbit/s always-on internet connection. + - Linux OS (Ubuntu 18.04 or 20.04 recommended)/MacOS. + +Uptime in incredibly important for being a validator. It is expected that validators will have appropriate redundancies for compute, power, connectivity etc. While the blockchain itself it highly replicated it is also expected that validators will perform local storage backups in order to minimise validator down time. + +## Set up a website + +Set up a dedicated validator's website and signal your intention to become a validator on our [Discord ↗️](https://discord.com/invite/fetchai) server. This is important since delegators will want to have information about the entity they are delegating their FET to. + +Strictly speaking this is not necessary, however, it is recommended. As a validator on the network you will want to get other community users to delegate stake to your validator. The more combined stake that a validate has then the great share of the block rewards they will take. + +## Seek Legal Advice + +Seek legal advice if you intend to run a Validator. + +## Community + +We highly recommend to check out the validator community on the discord channel for more information and to see that latest announcements about becoming a validator. + +* [Discord ↗️](https://discord.com/invite/fetchai) diff --git a/pages/guides.mdx b/pages/guides.mdx index 5d126d2d9..1e70e715e 100644 --- a/pages/guides.mdx +++ b/pages/guides.mdx @@ -292,6 +292,38 @@ import { GuideBox } from "../components/feature-guide-tabs"; +## Ledger + +
+ A list of guides related to operations executable on the Fetch Ledger. +
+ + + + + + + + + ## Integrations diff --git a/pages/guides/_meta.json b/pages/guides/_meta.json index e86cc32aa..bc38441f0 100644 --- a/pages/guides/_meta.json +++ b/pages/guides/_meta.json @@ -2,5 +2,6 @@ "agents": "uAgents", "agentverse": "Agentverse", "fetch-network": "Fetch Network", + "ledger": "Ledger", "integrations": "Integrations" } diff --git a/pages/guides/ledger/_meta.json b/pages/guides/ledger/_meta.json new file mode 100644 index 000000000..924418513 --- /dev/null +++ b/pages/guides/ledger/_meta.json @@ -0,0 +1,11 @@ +{ + "installation": "Installation", + "snapshots": "Chain state snapshots", + "state-sync": "State-sync", + "setup-validator-node": "Setting up a validator node", + "joining-testnet": "Joining a testnet", + "single-node-testnet": "Running a single node network", + "governance": "Governance", + "faucet": "Token Faucet", + "cli": "Command Line Interface" +} diff --git a/pages/guides/ledger/cli/_meta.json b/pages/guides/ledger/cli/_meta.json new file mode 100644 index 000000000..461e5f1a8 --- /dev/null +++ b/pages/guides/ledger/cli/_meta.json @@ -0,0 +1,8 @@ +{ + "intro": "CLI - Introduction", + "keys": "CLI - Managing keys", + "tokens": "CLI - Managing tokens", + "multisig-keys": "CLI - Multisig keys", + "delegator": "CLI - Delegator guide", + "governance-proposals": "Governance proposals" +} diff --git a/pages/references.mdx b/pages/references.mdx index f622c9b7f..5c5c4e55e 100644 --- a/pages/references.mdx +++ b/pages/references.mdx @@ -69,4 +69,45 @@ import { GuideBox } from "../components/feature-guide-tabs"; +## Ledger + + + + + + + + + + + + + + + +
diff --git a/pages/references/_meta.json b/pages/references/_meta.json index fec5f998d..fbc9b72e3 100644 --- a/pages/references/_meta.json +++ b/pages/references/_meta.json @@ -1,4 +1,5 @@ { "contracts": "Contracts", - "uagents": "uAgents" + "uagents": "uAgents", + "ledger": "Ledger" } diff --git a/pages/references/ledger/_meta.json b/pages/references/ledger/_meta.json new file mode 100644 index 000000000..f7f77e76a --- /dev/null +++ b/pages/references/ledger/_meta.json @@ -0,0 +1,6 @@ +{ + "versions": "Versions", + "active-networks": "Active networks", + "mainnet-archive": "Mainnet archives \uD83D\uDDC4", + "security": "Validators security" +} diff --git a/pages/references/ledger/active-networks.mdx b/pages/references/ledger/active-networks.mdx new file mode 100644 index 000000000..920a8b6c1 --- /dev/null +++ b/pages/references/ledger/active-networks.mdx @@ -0,0 +1,51 @@ +# Active networks + +## Mainnet + +The chain identifier of our production network is fetchhub-4. + +| Parameter | Value | +| :------------- | -----: | +| Chain ID | fetchhub-4 | +| Block range | 5,300,201 --> | +| Date range | 05/04/2022 --> | +| Denomination | afet | +| Decimals | 18 (1fet = 1000000000000000000afet) | +| Version | [v0.10.3 ↗️](https://github.com/fetchai/fetchd/releases/tag/v0.10.3) up to block 6295500 | +| | [v0.10.4 ↗️](https://github.com/fetchai/fetchd/releases/tag/v0.10.4) up to block 7305500 | +| | [v0.10.5 ↗️](https://github.com/fetchai/fetchd/releases/tag/v0.10.5) for blocks > 7305500| +| RPC Endpoint | [https://rpc-fetchhub.fetch.ai:443 ↗️](https://rpc-fetchhub.fetch.ai:443) | +| GRPC Endpoint | [https://grpc-fetchhub.fetch.ai:443 ↗️](https://grpc-fetchhub.fetch.ai:443) | +| REST Endpoint | [https://grpc-fetchhub.fetch.ai:443 ↗️](https://rest-fetchhub.fetch.ai:443) | +| Block Explorer | [https://explore-fetchhub.fetch.ai ↗️](https://explore-fetchhub.fetch.ai) | +| Token Faucet | N/A | +| Genesis | `curl https://raw.githubusercontent.com/fetchai/genesis-fetchhub/fetchhub-4/fetchhub-4/data/genesis_migrated_5300200.json --output ~/.fetchd/config/genesis.json` | +| Seed Node(s) | 17693da418c15c95d629994a320e2c4f51a8069b@connect-fetchhub.fetch.ai:36456,a575c681c2861fe945f77cb3aba0357da294f1f2@connect-fetchhub.fetch.ai:36457,d7cda986c9f59ab9e05058a803c3d0300d15d8da@connect-fetchhub.fetch.ai:36458 | +| Snapshots | [https://storage.googleapis.com/fetch-ai-mainnet-snapshots/fetchhub-4-pruned.tgz ↗️](https://storage.googleapis.com/fetch-ai-mainnet-snapshots/fetchhub-4-pruned.tgz)
[https://storage.googleapis.com/fetch-ai-mainnet-snapshots/fetchhub-4-full.tgz ↗️](https://storage.googleapis.com/fetch-ai-mainnet-snapshots/fetchhub-4-full.tgz)
[https://storage.googleapis.com/fetch-ai-mainnet-snapshots/fetchhub-4-archive.tgz ↗️](https://storage.googleapis.com/fetch-ai-mainnet-snapshots/fetchhub-4-archive.tgz) | + +## Test Nets + +### Dorado + +This network is running the same major version of fetchd as our mainnet (`fetchhub-4`), possibly at a more recent minor version. + +It is stable for deploying smart contracts and testing IBC. + +| Parameter | Value | +| :-------------- | ------: | +| Chain ID | dorado-1 | +| Denomination | atestfet | +| Decimals | 18 (1testfet = 1000000000000000000atestfet) | +| Min Gas Prices | 1000000000atestfet | +| Version | [v0.10.3 ↗️](https://github.com/fetchai/fetchd/releases/tag/v0.10.3) up to block 947800 | +| | [v0.10.4 ↗️](https://github.com/fetchai/fetchd/releases/tag/v0.10.4) for blocks > 947800 and < 2198000 | +| | [v0.10.5 ↗️](https://github.com/fetchai/fetchd/releases/tag/v0.10.5) for blocks > 2198000 | +| RPC Endpoint | [https://rpc-dorado.fetch.ai:443 ↗️](https://rpc-dorado.fetch.ai:443) | +| GRPC Endpoint | [https://grpc-dorado.fetch.ai:443 ↗️](https://grpc-dorado.fetch.ai:443) | +| REST Endpoint | [https://rest-dorado.fetch.ai:443 ↗️](https://rest-dorado.fetch.ai:443) | +| Block Explorer | [https://explore-dorado.fetch.ai/ ↗️](https://explore-dorado.fetch.ai/) | +| Ledger Explorer | [https://browse-dorado.fetch.ai/ ↗️](https://browse-dorado.fetch.ai/) | +| Token Faucet | Use block explorer | +| Genesis | `curl https://storage.googleapis.com/fetch-ai-testnet-genesis/genesis-dorado-827201.json --output ~/.fetchd/config/genesis.json` | +| Seed Node(s) | eb9b9717975b49a57e62ea93aa4480e091ae0660@connect-dorado.fetch.ai:36556,46d2f86a255ece3daf244e2ca11d5be0f16cb633@connect-dorado.fetch.ai:36557,066fc564979b1f3173615f101b62448ac7e00eb1@connect-dorado.fetch.ai:36558 | +| Snapshots | [https://storage.googleapis.com/fetch-ai-testnet-snapshots/dorado-pruned.tgz ↗️](https://storage.googleapis.com/fetch-ai-testnet-snapshots/dorado-pruned.tgz)
[https://storage.googleapis.com/fetch-ai-testnet-snapshots/dorado-full.tgz ↗️](https://storage.googleapis.com/fetch-ai-testnet-snapshots/dorado-full.tgz)
[https://storage.googleapis.com/fetch-ai-testnet-snapshots/dorado-archive.tgz ↗️](https://storage.googleapis.com/fetch-ai-testnet-snapshots/dorado-archive.tgz) | diff --git a/pages/references/ledger/mainnet-archive.mdx b/pages/references/ledger/mainnet-archive.mdx new file mode 100644 index 000000000..093d283cb --- /dev/null +++ b/pages/references/ledger/mainnet-archive.mdx @@ -0,0 +1,59 @@ +# Mainnet archives 🗄 + +Archived data from previous versions of the fetchhub mainnet. + +## Fetchhub-3 archive + +| Parameter | Value | +| :------------- | -----------------------------------------------------------------------------------------------: | +| Chain ID | fetchhub-3 | +| Block range | 4,504,601 --> 5,300,200 | +| Date range | 08/02/2022 --> 05/04/2022 | +| Denomination | afet | +| Decimals | 18 (1fet = 1000000000000000000afet) | +| Version | [v0.9.1 ↗️](https://github.com/fetchai/fetchd/releases/tag/v0.9.1) | +| RPC Endpoint | [here ↗️](https://rpc-fetchhub3-archive.fetch.ai:443) | +| GRPC Endpoint | [here ↗️](https://grpc-fetchhub3-archive.fetch.ai:443) | +| REST Endpoint | [here ↗️](https://rest-fetchhub3-archive.fetch.ai:443) | +| Block Explorer | [here ↗️](https://explore-fetchhub3-archive.fetch.ai) | +| Token Faucet | N/A | +| Seed Node(s) | N/A | +| Snapshots | [here ↗️](https://storage.googleapis.com/fetch-ai-mainnet-snapshots/fetchhub-3-archive.tgz) | + + +### Fetchhub-2 archive + +| Parameter | Value | +| :------------- | -------------------------------------------------------------------------------------------: | +| Chain ID | fetchhub-2 | +| Block range | 2,436,701 --> 4,504,600 | +| Date range | 15/09/2021 --> 08/02/2022 | +| Denomination | afet | +| Decimals | 18 (1fet = 1000000000000000000afet) | +| Version | [v0.8.7 ↗️](https://github.com/fetchai/fetchd/releases/tag/v0.8.7) | +| RPC Endpoint | [here ↗️](https://rpc-fetchhub2-archive.fetch.ai:443) | +| GRPC Endpoint | [here ↗️](https://grpc-fetchhub2-archive.fetch.ai:443) | +| REST Endpoint | [here ↗️](https://rest-fetchhub2-archive.fetch.ai:443) | +| Block Explorer | [here ↗️](https://explore-fetchhub2-archive.fetch.ai) | +| Token Faucet | N/A | +| Seed Node(s) | N/A | +| Snapshots | [here ↗️](https://storage.googleapis.com/fetch-ai-mainnet-snapshots/fetchhub-2-archive.tgz) | + +### Fetchhub-1 archive + +| Parameter | Value | +| :------------- | ------------------------------------------------------------------------------------------: | +| Chain ID | fetchhub-1 | +| Block range | 1 --> 2,436,700 | +| Date range | 31/03/2021 --> 15/09/2021 | +| Denomination | afet | +| Decimals | 18 (1fet = 1000000000000000000afet) | +| Version | [v0.7.4 ↗️](https://github.com/fetchai/fetchd/releases/tag/v0.7.4) | +| RPC Endpoint | [here ↗️](https://rpc-fetchhub1-archive.fetch.ai:443) | +| GRPC Endpoint | N/A | +| REST Endpoint | [here ↗️](https://rest-fetchhub1-archive.fetch.ai:443) | +| Block Explorer | [here ↗️](https://explore-fetchhub1-archive.fetch.ai) | +| Token Faucet | N/A | +| Seed Node(s) | N/A | +| Snapshots | [here ↗️](https://storage.googleapis.com/fetch-ai-mainnet-snapshots/fetchhub-1-archive.tgz) | + diff --git a/pages/references/ledger/security.mdx b/pages/references/ledger/security.mdx new file mode 100644 index 000000000..9b955be08 --- /dev/null +++ b/pages/references/ledger/security.mdx @@ -0,0 +1,39 @@ +# Validator security + +Each validator candidate is encouraged to run its operations independently, as diverse setups increase the resilience of the network. Validator candidates should commence their setup phase now in order to be on time for launch. + +## Key management - HSM + +It is mission critical that an attacker cannot steal a validator's key. If this is possible, it puts the entire stake delegated to the compromised validator at risk. Hardware security modules are an important strategy for mitigating this risk. HSM modules must support `ed25519` signatures. + +## Sentry nodes (DDOS protection) + +Validators are responsible for ensuring that the network can sustain denial of service attacks. + +One recommended way to mitigate these risks is for validators is to carefully structure their network topology in a so-called sentry node architecture. + +Validator nodes should only connect to full-nodes they trust because they operate them themselves or are run by other validators they know socially. This architecture shifts the burden of denial-of-service from the validator's node directly to its sentry nodes, and may require new sentry nodes be spun up or activated to mitigate attacks on existing ones. + +Sentry nodes can be quickly spun up or change their IP addresses. Because the links to the sentry nodes are in private IP space, an internet based attacked cannot disturb them directly. This will ensure validator block proposals and votes always make it to the rest of the network. + +To setup your sentry node architecture, you can follow the instructions provided below: + +- Validators nodes should edit their `config.toml`: + + ```bash + # Comma separated list of nodes to keep persistent connections to + # Do not add private peers to this list if you don't want them advertised + persistent_peers =[list of sentry nodes] + + # Set true to enable the peer-exchange reactor + pex = false + ``` + +- Sentry nodes should edit their `config.toml`: + + ```bash + # Comma separated list of peer IDs to keep private (will not be gossiped to other peers) + # Example ID: 3e16af0cead27979e1fc3dac57d03df3c7a77acc@3.87.179.235:26656 + + private_peer_ids = "node_ids_of_private_peers" + ``` diff --git a/pages/references/ledger/versions.mdx b/pages/references/ledger/versions.mdx new file mode 100644 index 000000000..f3fcb14c0 --- /dev/null +++ b/pages/references/ledger/versions.mdx @@ -0,0 +1,19 @@ +# Versions + +There are multiple versions of the fetchd software with differing levels of features and maturity. The following table outlines the rough overview of these versions: + +| Version | Maturity | Description | +| :----------: | :--------: | :---------------------------------------------------------------------------------------| +| v0.2.x | Deprecated | This is a stable version of the network to support agent development | +| v0.3.x | Deprecated | Builds upon our stable release and adds support for the random beacon consensus module | +| v0.4.x | Deprecated | Builds upon the random beacon consensus and adds support for aggregated signatures | +| v0.5.x | Deprecated | Extension of v0.4.x | +| v0.6.x | Deprecated | Extension of v0.5.x | +| v0.7.x | Deprecated | Pre stargate fetchhub mainnet version | +| v0.8.x | Deprecated | Mainline version of the network used for **Stargate** fetchhub mainnet | +| v0.9.x | Deprecated | Mainline version of the network used for **Capricorn** fetchhub mainnet | +| v0.10.x | Stable | Mainline version of the network used for **Dorado** fetchhub mainnet | + +# Upgrade history + +For node operators, the full upgrade history, documentations and procedures are available at: [https://github.com/fetchai/genesis-fetchhub ↗️](https://github.com/fetchai/genesis-fetchhub). \ No newline at end of file From f88b6137b68959b1e843f91e4ceae861ac0c4a0c Mon Sep 17 00:00:00 2001 From: Felix Nicolae Bucsa Date: Tue, 19 Sep 2023 14:38:35 +0100 Subject: [PATCH 02/26] edits: added guides in guides for ledger --- pages/concepts.mdx | 1 - pages/guides/ledger/cli/delegator.mdx | 1 + pages/guides/ledger/cli/governance-proposals.mdx | 0 pages/guides/ledger/cli/intro.mdx | 0 pages/guides/ledger/cli/keys.mdx | 0 pages/guides/ledger/cli/multisig-keys.mdx | 0 pages/guides/ledger/cli/tokens.mdx | 0 pages/guides/ledger/faucet.mdx | 0 pages/guides/ledger/governance.mdx | 0 pages/guides/ledger/installation.mdx | 0 pages/guides/ledger/joining-testnet.mdx | 0 pages/guides/ledger/setup-validator-node.mdx | 0 pages/guides/ledger/single-node-testnet.mdx | 0 pages/guides/ledger/snapshots.mdx | 0 pages/guides/ledger/state-sync.mdx | 0 15 files changed, 1 insertion(+), 1 deletion(-) create mode 100644 pages/guides/ledger/cli/delegator.mdx create mode 100644 pages/guides/ledger/cli/governance-proposals.mdx create mode 100644 pages/guides/ledger/cli/intro.mdx create mode 100644 pages/guides/ledger/cli/keys.mdx create mode 100644 pages/guides/ledger/cli/multisig-keys.mdx create mode 100644 pages/guides/ledger/cli/tokens.mdx create mode 100644 pages/guides/ledger/faucet.mdx create mode 100644 pages/guides/ledger/governance.mdx create mode 100644 pages/guides/ledger/installation.mdx create mode 100644 pages/guides/ledger/joining-testnet.mdx create mode 100644 pages/guides/ledger/setup-validator-node.mdx create mode 100644 pages/guides/ledger/single-node-testnet.mdx create mode 100644 pages/guides/ledger/snapshots.mdx create mode 100644 pages/guides/ledger/state-sync.mdx diff --git a/pages/concepts.mdx b/pages/concepts.mdx index 5a8797e23..4cdf45fa6 100644 --- a/pages/concepts.mdx +++ b/pages/concepts.mdx @@ -147,7 +147,6 @@ import { GuideBox } from "../components/feature-guide-tabs"; /> - Date: Wed, 20 Sep 2023 14:51:22 +0100 Subject: [PATCH 03/26] edits: started adding ledger guides in docs --- pages/guides.mdx | 28 +++++- pages/guides/ledger/_meta.json | 4 +- pages/guides/ledger/installation.mdx | 71 +++++++++++++++ pages/guides/ledger/snapshots.mdx | 61 +++++++++++++ pages/guides/ledger/state-sync.mdx | 128 +++++++++++++++++++++++++++ 5 files changed, 289 insertions(+), 3 deletions(-) diff --git a/pages/guides.mdx b/pages/guides.mdx index 7fcd66993..7fd446fb0 100644 --- a/pages/guides.mdx +++ b/pages/guides.mdx @@ -425,6 +425,31 @@ import { GuideBox } from "../components/feature-guide-tabs"; A list of guides related to operations executable on the Fetch Ledger. + + + + + + + + ## Integrations diff --git a/pages/guides/ledger/_meta.json b/pages/guides/ledger/_meta.json index 924418513..5545c36de 100644 --- a/pages/guides/ledger/_meta.json +++ b/pages/guides/ledger/_meta.json @@ -1,6 +1,6 @@ { - "installation": "Installation", - "snapshots": "Chain state snapshots", + "installation": "Installation \uD83D\uDEE0", + "snapshots": "How to use chain state snapshots", "state-sync": "State-sync", "setup-validator-node": "Setting up a validator node", "joining-testnet": "Joining a testnet", diff --git a/pages/guides/ledger/installation.mdx b/pages/guides/ledger/installation.mdx index e69de29bb..28cc661ed 100644 --- a/pages/guides/ledger/installation.mdx +++ b/pages/guides/ledger/installation.mdx @@ -0,0 +1,71 @@ +import { Callout } from 'nextra/components' + +# Installation 🛠 + +## Prerequisites + + - **Go 1.18+**: installation instructions available [here ↗️](https://golang.org/dl/). + - **Packages**: `make`, `gcc` (on Ubuntu, install them with `sudo apt-get update && sudo apt-get install -y make gcc`). + +## Building the code + +Download the latest released version from GitHub and build the project using the running the following command: + + ``` + git clone https://github.com/fetchai/fetchd.git && cd fetchd + ``` + +Then, build the code by running the follwoing command: + + ```bash + make build + ``` + + This will generate the `./build/fetchd` binary. + +For non-developer users we recommend that the user installs the binaries into their system. This can be done with the following command: + + ```bash + make install + ``` + + This will install the binaries in the directory specified by your `$GOBIN` environment variable (default to `~/go/bin`). + + ```bash + which fetchd + ``` + + This should return a path such as `~/go/bin/fetchd` (might be different depending on your actual **Go** installation). + + + If you get no output, or an error such as `which: no fetchd in ...`, possible cause can either be that `make install` failed with some errors or that your go binary folder (default: ~/go/bin) is not in your `PATH`. + + To add the ~/go/bin folder to your PATH, add this line at the end of your ~/.bashrc: + + ``` + export PATH=$PATH:~/go/bin + ``` + and reload it with: + + ``` + source ~/.bashrc + ``` + + +You can also verify that you are running the correct version: + + ```bash + fetchd version + ``` + +This should print a version number that must be compatible with the network you're connecting to. See the [network page ↗️](/references/ledger/active-networks) for the list of supported versions per network. + +### FAQ + +**Error: failed to parse log level (main:info,state:info,:error): Unknown Level String: 'main:info,state:info,:error', defaulting to NoLevel** + +This means you had a pre-stargate version of fetchd (≤ v0.7.x), and just installed a stargate version (≥ v0.8.x), you will need to remove the previous configuration files with: + + ```bash + rm ~/.fetchd/config/app.toml ~/.fetchd/config/config.toml + ``` \ No newline at end of file diff --git a/pages/guides/ledger/snapshots.mdx b/pages/guides/ledger/snapshots.mdx index e69de29bb..f8186c70f 100644 --- a/pages/guides/ledger/snapshots.mdx +++ b/pages/guides/ledger/snapshots.mdx @@ -0,0 +1,61 @@ +import { Callout } from 'nextra/components' + +# Chain state snapshots + +As blockchains get longer, the process of syncing from the genesis block begins to take many hours, or even days to complete. + +In circumstances where a faster sync is required, various snapshots of the fetchd chain state data are available for download, to more quickly bootstrap a node. + +Snapshots are available for both mainnet and the most recent testnet. The URLs can be obtained from the [active network page ↗️](/references/ledger/active-networks). **We aim to update snapshots on a daily basis**. + +The example below uses the _pruned mainnet snapshot_, but can be adapted as required for full or archive nodes. + +## Using a snapshot + +### Stop your node + +If you are already running fetchd, it is important that you stop it before proceeding. + +Instructions for this are highly installation dependent and beyond the scope of this document, but could be as simple as a Ctrl-C. + +If you have not already initialised your node, follow the instructions for [joining a testnet ↗️](/guides/ledger/joining-testnet) then return to this page before starting fetchd. **Remember to modify the information for the mainnet as appropriate**. + +### Reset your node + + + This will irreversibly erase your node's state database. Ensure you take whatever backups you deem appropriate before proceeding. + + +- If using fetchd ≤ 0.10.3: `fetchd unsafe-reset-all` + +- If using fetchd ≥ 0.10.4: `fetchd tendermint unsafe-reset-all` + +### Download and install the snapshot + +**Many options are available here!** + +The example below assumes a bash-like environment, uses a single connection for downloading, confirms the md5sum of the downloaded data against that of the original, and does not land the original compressed data to disk. This is a good starting point, but depending on your local environment you may wish to make adaptations that eg sacrifice disk space and extra md5sum complexity for the benefit of parallel downloads with aria2. + +Entirely up to you! let us know how you get on! + + ```bash + # (optional) show the timestamp of the latest available snapshot + echo "Latest available snapshot timestamp : $(curl -s -I https://storage.googleapis.com/fetch-ai-mainnet-snapshots/fetchhub-4-pruned.tgz | grep last-modified | cut -f3- -d' ')" + + # download, decompress and extract state database + curl -v https://storage.googleapis.com/fetch-ai-mainnet-snapshots/fetchhub-4-pruned.tgz -o- 2>headers.out | tee >(md5sum > md5sum.out) | gunzip -c | tar -xvf - --directory=~/.fetchd + + # (optional, but recommended) compare source md5 checksum provided in the headers by google, with the one calculated locally + [[ $(grep 'x-goog-hash: md5' headers.out | sed -z 's/^.*md5=\(.*\)/\1/g' | tr -d '\r' | base64 -d | od -An -vtx1 | tr -d ' \n') == $(awk '{ print $1 }' md5sum.out) ]] && echo "OK - md5sum match" || echo "ERROR - md5sum MISMATCH" + + # (optional) show the creation date of the downloaded snapshot + echo "Downloaded snapshot timestamp: $(grep last-modified headers.out | cut -f3- -d' ')" + ``` + +### Restart your node + +Again, this entirely depends on your local installation, but a simple example for mainnet might be the following: + + ```bash + fetchd start --p2p.seeds 17693da418c15c95d629994a320e2c4f51a8069b@connect-fetchhub.fetch.ai:36456,a575c681c2861fe945f77cb3aba0357da294f1f2@connect-fetchhub.fetch.ai:36457,d7cda986c9f59ab9e05058a803c3d0300d15d8da@connect-fetchhub.fetch.ai:36458`. + ``` diff --git a/pages/guides/ledger/state-sync.mdx b/pages/guides/ledger/state-sync.mdx index e69de29bb..cb829bd2c 100644 --- a/pages/guides/ledger/state-sync.mdx +++ b/pages/guides/ledger/state-sync.mdx @@ -0,0 +1,128 @@ +import { Callout } from 'nextra/components' + +# State-sync + +**State sync** is a feature which allows you to quickly bootstrap a new node by allowing it to pull a _state snapshot_ taken by other nodes. + + + The state sync feature is only available from `fetchd v0.10.6` and later. Prior versions needed to either sync from scratch or restore a [chain snapshot ↗️](/guides/ledger/snapshots), which both could take hours before having the node fully synced. + + +With state sync, it now takes only a few minutes before having an operational node. + +## Configuring the new node + +In order to instruct the node to sync itself using a state sync snapshot, it need some configuration in the `~/.fetchd/config/config.toml` file. + +Open this file in an editor and lookup for the `statesync` section. + +By default, it should looks like this: + + ```yaml + ####################################################### + ### State Sync Configuration Options ### + ####################################################### + + [statesync] + # State sync rapidly bootstraps a new node by discovering, fetching, and restoring a state machine + # snapshot from peers instead of fetching and replaying historical blocks. Requires some peers in + # the network to take and serve state machine snapshots. State sync is not attempted if the node + # has any local state (LastBlockHeight > 0). The node will have a truncated block history, + # starting from the height of the snapshot. + enable = false + + # RPC servers (comma-separated) for light client verification of the synced state machine and + # retrieval of state data for node bootstrapping. Also needs a trusted height and corresponding + # header hash obtained from a trusted source, and a period during which validators can be trusted. + + # For Cosmos SDK-based chains, trust_period should usually be about 2/3 of the unbonding time (~2 + # weeks) during which they can be financially punished (slashed) for misbehavior. + rpc_servers = "" + trust_height = 0 + trust_hash = "" + trust_period = "168h0m0s" + + # Time to spend discovering snapshots before initiating a restore. + discovery_time = "15s" + + # Temporary directory for state sync snapshot chunks, defaults to the OS tempdir (typically /tmp). + # Will create a new, randomly named directory within, and remove it when done. + temp_dir = "" + + # The timeout duration before re-requesting a chunk, possibly from a different + # peer (default: 1 minute). + chunk_request_timeout = "10s" + + # The number of concurrent chunk fetchers to run (default: 1). + chunk_fetchers = "4" + ``` + +A few changes are needed: + + - First, set `enable = true` to activate the state sync engine. + + - Then, **at least 2** rpc servers must be provided. A good place to find some is the [cosmos chain registry ↗️](https://github.com/cosmos/chain-registry/blob/master/fetchhub/chain.json#L62). Servers must be comma separated without space (i.e., `rpc_servers = "https://rpc-fetchhub.fetch.ai:443,https://fetch-rpc.polkachu.com:443"`). These servers will be used to verify the snapshots, so make sure you trust them enough for this. + + - a *recent* `trust_height` and `trust_hash` are needed. Recent means it must be contained in the `trust_period` (168 hours, or ~1 week old by default). These can be obtained from a RPC server **you trust to provide you correct data** (and the 2nd RPC server from `rpc_servers` will be charged of confirming that the data are correct). + + - And last, set `chunk_request_timeout` to `60s` (the `10s` default value seems too short and can lead to "context deadline exceeded" timeout errors when verifying the hashes) + +To retrieve the correct value for a **Fetch.ai RPC server**, and the current network height, use: + + ```bash + curl https://rpc-fetchhub.fetch.ai:443/block | jq -r '{"trusted_hash": .result.block_id.hash, "trusted_height": .result.block.header.height}' + { + "trusted_hash": "...some hash...", + "trusted_height": "...some height..." + } + ``` + +and set the `trusted_hash` and `trusted_height` values in the config file. + +Once this is set, make sure you have the correct genesis by downloading it from the RPC node: + + ```bash + curl https://raw.githubusercontent.com/fetchai/genesis-fetchhub/fetchhub-4/fetchhub-4/data/genesis_migrated_5300200.json --output ~/.fetchd/config/genesis.json + ``` + +and start the node using the seeds from the chain-registry: + + ```bash + fetchd start --p2p.seeds="17693da418c15c95d629994a320e2c4f51a8069b@connect-fetchhub.fetch.ai:36456,a575c681c2861fe945f77cb3aba0357da294f1f2@connect-fetchhub.fetch.ai:36457,d7cda986c9f59ab9e05058a803c3d0300d15d8da@connect-fetchhub.fetch.ai:36458" + ``` + +After the node initialized, it will start searching for available snapshots, and it should print log messages similar to: + + ``` + 8:22AM INF Discovered new snapshot format=1 hash="� ݫ/��\r�F#C(pD�<��\x066��\x1f��\x1f Date: Wed, 20 Sep 2023 17:56:34 +0100 Subject: [PATCH 04/26] edits: added all ledger guides missing. Only CLI guides missing for now. --- pages/guides.mdx | 27 +++-- pages/guides/ledger/_meta.json | 6 +- pages/guides/ledger/faucet.mdx | 56 ++++++++++ pages/guides/ledger/governance.mdx | 103 +++++++++++++++++++ pages/guides/ledger/joining-testnet.mdx | 102 ++++++++++++++++++ pages/guides/ledger/setup-validator-node.mdx | 84 +++++++++++++++ pages/guides/ledger/single-node-testnet.mdx | 78 ++++++++++++++ 7 files changed, 444 insertions(+), 12 deletions(-) diff --git a/pages/guides.mdx b/pages/guides.mdx index 7fd446fb0..38ba0486b 100644 --- a/pages/guides.mdx +++ b/pages/guides.mdx @@ -453,29 +453,38 @@ import { GuideBox } from "../components/feature-guide-tabs"; + + + ## Integrations diff --git a/pages/guides/ledger/_meta.json b/pages/guides/ledger/_meta.json index 5545c36de..a324fc8bd 100644 --- a/pages/guides/ledger/_meta.json +++ b/pages/guides/ledger/_meta.json @@ -3,9 +3,9 @@ "snapshots": "How to use chain state snapshots", "state-sync": "State-sync", "setup-validator-node": "Setting up a validator node", - "joining-testnet": "Joining a testnet", - "single-node-testnet": "Running a single node network", + "joining-testnet": "How to join a testnet", + "single-node-testnet": "How to run a single node network", "governance": "Governance", - "faucet": "Token Faucet", + "faucet": "How to use the token faucet", "cli": "Command Line Interface" } diff --git a/pages/guides/ledger/faucet.mdx b/pages/guides/ledger/faucet.mdx index e69de29bb..970dc6bee 100644 --- a/pages/guides/ledger/faucet.mdx +++ b/pages/guides/ledger/faucet.mdx @@ -0,0 +1,56 @@ +# How to use the token faucet + +## Introduction + +For our test networks, we have a simple token faucet implemented to allow users of the network to get started quickly. You can send it an account address, and it will transfer some test token on it. + +Token Faucets are network specific, depending on the network type they may or may not be deployed. Please check the [networks ↗️](/references/ledger/active-networks) page for specific details. + +The token faucet itself is available from the network block explorer (`GET FUNDS` button on the homepage). + +Enter your `fetch...` address in the popup and click **Add funds** button. Wait a few blocks for the transaction to be processed, and you should see it appear along with some funds on your account. + +## Add funds to Wallet using faucet APIs + +You can also request and get testnet tokens in your wallet using the APIs. + +### Get some atestfet + + ```bash + curl -X POST -H 'Content-Type: application/json' -d '{"address":"
"}' https://faucet-dorado.fetch.ai/api/v3/claims + ``` + +### Get some nanomobx + + ```bash + curl -X POST -H 'Content-Type: application/json' -d '{"address":"
"}' https://faucet-mobx-dorado.fetch.ai/api/v3/claims + ``` + +### Get some ulrn + + ```bash + curl -X POST -H 'Content-Type: application/json' -d '{"address":"
"}' https://faucet-lrn-dorado.fetch.ai/api/v3/claims + ``` + +### Sample response for fund request to faucet + + ```text + {"status":"ok","uuid":"","target":"
"} + ``` + +### Check the wallet balance + + ```bash + fetchd query bank balances
+ ``` + +The output would be: + + ```text + balances: + - amount: "" + denom: atestfet + pagination: + next_key: null + total: "0" + ``` diff --git a/pages/guides/ledger/governance.mdx b/pages/guides/ledger/governance.mdx index e69de29bb..5ee309b6e 100644 --- a/pages/guides/ledger/governance.mdx +++ b/pages/guides/ledger/governance.mdx @@ -0,0 +1,103 @@ +import { Callout } from 'nextra/components' + +# Governance + +If you wish to take part in governance, you either need to be running a full validator node or you need to have have delegated stake to an existing validator. + +## Stake delegation + +If you want to delegate stake to a validator the following command should be used: + + ```bash + fetchd tx staking delegate --from + ``` + +where the `` begins with the prefix `fetchvaloper1...` and the `` field contains the currency denomination. + +For instance: + + ```bash + fetchd tx staking delegate fetchvaloper1cct4fhhksplu9m9wjljuthjqhjj93z0s97p3g7 1000atestfet --from agent + ``` + +## Proposals overview + +There are three types of proposal: + + 1. **Text proposals**: These are the most basic type of proposal. They can be used to get the opinion from participants of the network on a given topic. + 2. **Parameter proposals**: These proposals are used to update the value of an existing software parameter of the network. + 3. **Software upgrade proposals**: These are used to propose an upgrade of the `fetchd` software, particularly in cases where the software changes might not necessary be backwards compatible or in some way present a major update to the network. + +## The proposal process + +**Any FET holder can submit a proposal**. + +In order for the proposal to be open for voting, it needs to come with a deposit that is greater than a parameter called _minDeposit_. The deposit need not be provided in its entirety by the submitter. If the initial proposer's deposit is not sufficient, the proposal enters the **deposit period** status. Then, any FET holder can increase the deposit by sending a _depositTx_ transaction to the network. + +Once the deposit reaches _minDeposit_, the proposal enters the **voting period**, which lasts 2 weeks. Any bonded FET holder can then cast a vote on this proposal. The user has the following options for voting: + + * Yes + * No + * NoWithVeto + * Abstain + +At the end of the voting period, the proposal is accepted if there are **more than 50% Yes votes** (excluding Abstain votes) and **less than 33.33% of NoWithVeto votes** (excluding Abstain votes). + +## Generating proposals + +When creating a proposal, the user will create a proposal **JSON file** with all the relevant information. + +An example of a **text proposal** is shown below: + + ```json + { + "title": "Switch to semantic commit messages for fetchd", + "description": "This proposal is advocating a switch to sematic commit messages\nYou can find the full discussion here: https://github.com/fetchai/fetchd/issues/231", + "type": "Text", + "deposit": "10000000000000000000atestfet" + } + ``` + + + It is always recommended that the description of a text proposal has a link to a Github issue with the full proposal text along with the discussions about it. + + +After having created the JSON file, **the user can generate the text proposal on chain** by running the following command: + + `fetchd tx gov submit-proposal --proposal proposal.json --from ` + +## Increasing the deposit for a proposal + +If a user wants to **increase the deposit of a proposal**, they would run the following command: + + `fetchd tx gov deposit 100atestfet --from ` + +For example: + + `fetchd tx gov deposit 2 100atestfet --from validator` + +To get the **proposalID**, use the **txhash** obtained when the proposal was submitted and run the following command: + + `fetchd query tx ` + +## Listing current proposals + +Current proposals are visible from the block explorer and using the CLI. + +If you wish to get the list of current proposals and their corresponding _proposal-ids_ the run the following command: + + `fetchd query gov proposals` + +## Voting on a proposal + +If you want to vote for a proposal, run the following command: + + `fetchd tx gov vote