From 3e3cc6b1bb94d517157776e3967998c891cf9081 Mon Sep 17 00:00:00 2001 From: axenteoctavian Date: Tue, 14 Jan 2025 18:11:06 +0200 Subject: [PATCH 1/3] sovereign setup guides and services documentation --- docs/sovereign/custom-configurations.md | 38 ++++ docs/sovereign/deployment.md | 6 - docs/sovereign/distributed-setup.md | 210 ++++++++++++++++++++ docs/sovereign/{setup.md => local-setup.md} | 83 ++++---- docs/sovereign/one-click-setup.md | 13 ++ docs/sovereign/sovereign-api.md | 55 +++++ docs/sovereign/sovereign-explorer.md | 27 +++ docs/sovereign/sovereign-wallet.md | 32 +++ sidebars.js | 19 +- 9 files changed, 427 insertions(+), 56 deletions(-) create mode 100644 docs/sovereign/custom-configurations.md delete mode 100644 docs/sovereign/deployment.md create mode 100644 docs/sovereign/distributed-setup.md rename docs/sovereign/{setup.md => local-setup.md} (64%) create mode 100644 docs/sovereign/one-click-setup.md create mode 100644 docs/sovereign/sovereign-api.md create mode 100644 docs/sovereign/sovereign-explorer.md create mode 100644 docs/sovereign/sovereign-wallet.md diff --git a/docs/sovereign/custom-configurations.md b/docs/sovereign/custom-configurations.md new file mode 100644 index 000000000..ceba5e916 --- /dev/null +++ b/docs/sovereign/custom-configurations.md @@ -0,0 +1,38 @@ +# Custom Configurations + +## Sovereign network customisations + +The Sovereign Chain SDK is built with flexibility in mind, allowing you to tailor it to your specific needs. This page highlights various customizations you can apply to make your network unique. + +### config.toml + +- `GeneralSettings.ChainID` - defines your unique chain identifier +- `EpochStartConfig.RoundsPerEpoch` - defines how many round are in each epoch + +### economics.toml + +- `GlobalSettings.GenesisTotalSupply` - total native ESDT supply at genesis +- `GlobalSettings.YearSettings` - adjust the inflation rate each year +- `FeeSettings` - adjust the fee settings as needed + +### ratings.toml + +- `General` - adjust the rating parameters as needed + +### systemSmartContractsConfig.toml + +- `ESDTSystemSCConfig.ESDTPrefix` - the prefix for all issued tokens +- `ESDTSystemSCConfig.BaseIssuingCost` - base cost for issuing a token +- `StakingSystemSCConfig.NodeLimitPercentage` [[docs](https://docs.multiversx.com/validators/staking-v4/#how-does-the-dynamic-node-limitation-work)] + +### sovereignConfig.toml + +- `GenesisConfig.NativeESDT` - Native ESDT identifier for the sovereign chain + +### prefs.toml + +The `OverridableConfigTomlValues` will overwrite the parameters in the config files. Make sure that your new config parameters are not overwritten by this file. + +:::note +These are just a few examples that you can adjust to make the sovereign chain unique. All the files you could adjust when creating a sovereign chain can be found in the [deployment guide](/sovereign/distributed-setup#step-4-edit-the-sovereign-configuration). +::: diff --git a/docs/sovereign/deployment.md b/docs/sovereign/deployment.md deleted file mode 100644 index 1f83afa86..000000000 --- a/docs/sovereign/deployment.md +++ /dev/null @@ -1,6 +0,0 @@ -# Custom Configurations - -:::note -This version of the documentation focuses solely on the essential steps required to set up and deploy a sovereign chain on either a local or remote computer. More content will be added as it is accepted and discussed on [Agora](https://agora.multiversx.com/), or once it is implemented and available for production. -::: - diff --git a/docs/sovereign/distributed-setup.md b/docs/sovereign/distributed-setup.md new file mode 100644 index 000000000..2f1491a95 --- /dev/null +++ b/docs/sovereign/distributed-setup.md @@ -0,0 +1,210 @@ +# Distributed Setup Guide + +## Deploy distributed Sovereign Chain + +This guide will help you deploy a public Sovereign Chain with real validators. + +### Step 1: Get the ```mx-chain-go``` Repository + +Before proceeding, ensure that a **SSH key** for GitHub is configured on your machine. + +1. Clone the GitHub repository: + ```bash + git clone git@github.com:multiversx/mx-chain-go.git + ``` + +2. Checkout the specific sovereign chain sdk branch and navigate to testnet directory: + ```bash + cd mx-chain-go && git fetch && git checkout d699ffd6a29513c573b1d212861f932e037d8f67 && cd scripts/testnet + ``` + +:::info +`d699ffd6a29513c573b1d212861f932e037d8f67` is the commit hash we recommend to be used. If you want to use the latest version you can use the branch `feat/chain-go-sdk`. +::: + +### Step 2: Seeder Build + +Build and run the seed node +```bash +cd cmd/seednode +go build +./seednode -rest-api-interface 127.0.0.1:9091 -log-level *:DEBUG -log-save +``` + +The output will be something like this. The highlighted part is important and will be used later. + +| Seednode addresses: | +|---------------------------------------------------------------------------------------------| +| `/ip4/`127.0.0.1`/tcp/10000/p2p/16Uiu2HAmSY5NpuqC8UuFHunJensFbBc632zWnMPCYfM2wNLuvAvL` | +| `/ip4/`192.168.10.100`/tcp/10000/p2p/16Uiu2HAmSY5NpuqC8UuFHunJensFbBc632zWnMPCYfM2wNLuvAvL` | + + +### Step 3: Sovereign node build + +Build the sovereign node +```bash +cd cmd/sovereignnode/ +go build -v -ldflags="-X main.appVersion=v0.0.1" +``` + +:::info +Use your own custom version instead of `v0.0.1`. +::: + +### Step 4: Edit the sovereign configuration + +Node configs and be found in `cmd/node/config`. Below are the files and folders: +- gasSchedules folder +- genesisContracts folder +- genesis.json* +- genesisSmartContracts.json +- nodesSetup.json* +- api.toml +- config.toml +- economics.toml +- enableEpochs.toml +- enableRounds.toml +- external.toml +- fullArchiveP2P.toml +- p2p.toml +- prefs.toml +- ratings.toml +- systemSmartContractsConfig.toml + +_Note: Files marked with * will be discussed later in the document._ + +Sovereign configs can be found in `cmd/sovereignnode/config` +- economics.toml +- enableEpochs.toml +- prefs.toml +- sovereignConfig.toml + +#### Minimum recommended changes + +1. Move the config files from `/node/config` into `/sovereignnode/config`, except _economics.toml_, _enableEpochs.toml_, _prefs.toml_. +2. Config changes: + 1. **config.toml** + 1. GeneralSettings.ChainID + 2. EpochStartConfig.RoundsPerEpoch + 2. **p2p.toml** + 1. KadDhtPeerDiscovery:InitialPeerList = `[/ip4/PUBLIC_IP/tcp/10000/p2p/16Uiu2HAmSY5NpuqC8UuFHunJensFbBc632zWnMPCYfM2wNLuvAvL]` + - PUBLIC_IP is the IP of the machine where seed node is running, the other part is from seed node build + 3. **systemSmartContractsConfig.toml** + 1. ESDTSystemSCConfig.ESDTPrefix + 2. StakingSystemSCConfig.NodeLimitPercentage [[docs](https://docs.multiversx.com/validators/staking-v4/#how-does-the-dynamic-node-limitation-work)] + 4. **sovereignConfig.toml** + 1. GenesisConfig.NativeESDT +3. Other changes: + - Use the [custom configuration](/sovereign/deployment) page to see more configs we recommend to be changed + +### Step 5: Genesis configuration + +#### **genesis.json** + +This file should contain all the genesis addresses that will be funded and will be validators. Adjust as needed. + +:::note +The sum of `supply` should be equal to `GenesisTotalSupply` from economics.toml +::: + +Example with 2 validators: +``` +[ + { + "address": "erd1a2jq3rrqa0heta0fmlkrymky7yj247mrs54g6fyyx8dm45menkrsmu3dez", + "supply": "10000000000000000000000000", + "balance": "9997500000000000000000000", + "stakingvalue": "2500000000000000000000", + "delegation": { + "address": "", + "value": "0" + } + }, + { + "address": "erd1pn564xpwk4anq9z50th3ae99vplsf7d2p55cnugf00eu0gcq6gdqcg7ytx", + "supply": "10000000000000000000000000", + "balance": "9997500000000000000000000", + "stakingvalue": "2500000000000000000000", + "delegation": { + "address": "", + "value": "0" + } + } +] +``` + +#### **nodesSetup.json** + +This file contains all the initial nodes. Adjust as needed. + +:::note +- `consensusGroupSize` should be equal to `minNodesPerShard` +- each node pair contains one genesis address associated with a validator public key +- `startTime` should be a timestamp from the future, the time when the network will start +- `roundDuration` is the duration in milliseconds per round +- `metaChainConsensusGroupSize` and `metaChainMinNodes` should always be 0 +::: + +Example: +``` +{ + "startTime": 1733138599, + "roundDuration": 6000, + "consensusGroupSize": 2, + "minNodesPerShard": 2, + "metaChainConsensusGroupSize": 0, + "metaChainMinNodes": 0, + "hysteresis": 0, + "adaptivity": false, + "initialNodes": [ + { + "pubkey": "6a1ee46baa8da9279f53addbfbc61a525604eb42d964bd3a25bf7f34097c3b3a31706728718ccdbe3d43386c37ec3011df6ceb4188e14025ab149bd568cafaba18a78b51e71c24046c5276a187a6c1d6da83e30590a6025875b8f6df8984ec05", + "address": "erd1a2jq3rrqa0heta0fmlkrymky7yj247mrs54g6fyyx8dm45menkrsmu3dez", + "initialRating": 0 + }, + { + "pubkey": "40f3857218333f0b2ba8592fc053cbaebec8e1335f95957c89f6c601ce0758372ba31c30700f10f25202d8856bb948055f9f0ef53dea57b62f013ee01c9dc0346a2b3543f2b4d423166ee1981b310f2549fb879d4cd89de6c392d902a823d116", + "address": "erd1pn564xpwk4anq9z50th3ae99vplsf7d2p55cnugf00eu0gcq6gdqcg7ytx", + "initialRating": 0 + } + ] +} +``` + +___ + +At this point, a `config` folder should be created that will contain all the .toml files and genesis configuration. + +### Step 6: Validators setup + +#### Sovereign validator setup + +Each validator should have: +- **walletKey.pem** - wallet that will be funded at genesis +- **validatorKey.pem** (or **allValidatorsKey.pem** if multisig node) - validator pem used to deploy the node +- **config** folder + +#### Sovereign validator/observer node start + +The following commands will start the sovereign validator node with the configuration from **config** folder and with the **validatorKey** (or multi key from **allValidatorsKey**). +Adjust the flags as needed. You can find all the available flags in `/mx-chain-go/cmd/sovereignnode/flags.go` + +#### #single key +``` +./sovereignnode --validator-key-pem-file ./config/validatorKey.pem --profile-mode --log-save --log-level *:INFO --log-logger-name --log-correlation --use-health-service --rest-api-interface :8080 --working-directory ~/my_validator_node +``` + + +#### # multi key +``` +./sovereignnode --all-validator-keys-pem-file ./config/allValidatorsKey.pem --profile-mode --log-save --log-level *:INFO --log-logger-name --log-correlation --use-health-service --rest-api-interface :8080 --working-directory ~/my_validator_node +``` + +#### # observer +``` +./sovereignnode --profile-mode --log-save --log-level *:INFO --log-logger-name --log-correlation --use-health-service --rest-api-interface :8080 --working-directory ~/my_observer_node +``` + +## Deploy services + +You can find the documentation on how to deploy services at [this link](/sovereign/sovereign-api). diff --git a/docs/sovereign/setup.md b/docs/sovereign/local-setup.md similarity index 64% rename from docs/sovereign/setup.md rename to docs/sovereign/local-setup.md index f11c89451..fce7fc1c5 100644 --- a/docs/sovereign/setup.md +++ b/docs/sovereign/local-setup.md @@ -1,14 +1,10 @@ -# Setup Guide +# Full Local Setup Guide ## Deploy local Sovereign Chain -:::note - This guide is a preliminary version and not the final documentation for sovereign chains. It serves as a starting point for setting up a sovereign chain on a local machine. -::: +This guide will help you deploy a full sovereign local network connected to MultiversX network. This includes all the smart contracts and dependent services needed. Follow these steps carefully to ensure a successful deployment. -This guide will help you deploy contract on main chain, set up configuration files and deploy sovereign chain and all dependent services. Follow these steps carefully to ensure a successful deployment. - -## Step 1: Get the ```mx-chain-go``` Repository +### Step 1: Get the `mx-chain-go` Repository Before proceeding, ensure that a **SSH key** for GitHub is configured on your machine. @@ -19,15 +15,19 @@ Before proceeding, ensure that a **SSH key** for GitHub is configured on your ma 2. Checkout the specific sovereign chain sdk branch and navigate to testnet directory: ```bash - cd mx-chain-go && git fetch && git checkout feat/chain-go-sdk && cd scripts/testnet + cd mx-chain-go && git fetch && git checkout d699ffd6a29513c573b1d212861f932e037d8f67 && cd scripts/testnet ``` +:::info +`d699ffd6a29513c573b1d212861f932e037d8f67` is the commit hash we recommend to be used. If you want to use the latest version you can use the branch `feat/chain-go-sdk`. +::: + 3. Run the prerequisites script: ```bash ./prerequisites.sh ``` -:::note +:::info The prerequisites script verifies and downloads the necessary packages to run the nodes and clones the required repositories: - **mx-chain-deploy-go**: Initializes the configuration for the chain and deployment parameters. @@ -35,20 +35,19 @@ The prerequisites script verifies and downloads the necessary packages to run th - **mx-chain-sovereign-bridge-go**: Repository for the cross-chain service. ::: -## Step 2: Deploy Sovereign setup +### Step 2: Deploy Sovereign setup -First navigate to the sovereignBridge folder: - -```bash -cd sovereignBridge -``` +1. Navigate to the `sovereignBridge` folder: + ```bash + cd sovereignBridge + ``` -1. Install the [software dependencies](/sovereign/software-dependencies) and download the cross-chain contracts by running the sovereign bridge prerequisites script: +2. Install the [software dependencies](/sovereign/software-dependencies) and download the cross-chain contracts by running the sovereign bridge prerequisites script: ```bash ./prerequisites.sh ``` -2. Create a new wallet: +3. Create a new wallet: ```bash mxpy wallet new --format pem --outfile ~/wallet.pem ``` @@ -60,7 +59,7 @@ You can use any wallet of your choice, but for the purpose of this guide we are 3. Get funds in the wallet on the chain you want the sovereign to be connected to. 4. Update the configuration file `config/configs.cfg` with paths you want to use, wallet location and main chain constants. Example: - ```ini + ``` # Sovereign Paths SOVEREIGN_DIRECTORY="~/sovereign" TXS_OUTFILE_DIRECTORY="${SOVEREIGN_DIRECTORY}/txsOutput" @@ -78,10 +77,11 @@ You can use any wallet of your choice, but for the purpose of this guide we are - **SOVEREIGN_DIRECTORY, TXS_OUTFILE_DIRECTORY, CONTRACTS_DIRECTORY** - represent the paths to the location where the deploy scripts will generate the outputs. - **WALLET** - should represent the wallet generated at Step 1. - **PROXY** - in this case, for the purpose of the test, the used proxy is the testnet one. Of course that the proper proxy should be used when deploying your own set of contracts depending on the development phase of your project. -- **CHAIN_ID** - should represent the chain ID of the chain where the contracts are to be deployed. The currently supported constants are: +- **CHAIN_ID** - should represent the chain ID of the chain where the contracts are to be deployed. - **"1"** for Mainnet; - **"D"** for Devnet; - **"T"** for Testnet; + - or use you own local network ID ::: 5. Source the script: @@ -94,55 +94,42 @@ You can use any wallet of your choice, but for the purpose of this guide we are deploySovereignWithCrossChainContracts ``` -## Stop and clean local Sovereign Chain +:::info +`deploySovereignWithCrossChainContracts` command will: +- deploy all main chain smart contracts and update sovereign configs +- deploy sovereign nodes and the main chain observer +::: -1. Navigate to `/mx-chain-go/scripts/testnet/sovereignBridge`. +### Step 3: Deploy services - Source the script: - ```bash - source script.sh - ``` +You can find the documentation on how to deploy services [here](/sovereign/sovereign-api). -2. Stop and clean the chain with all dependent services: - ```bash - stopAndCleanSovereign - ``` +___ -## Upgrade and reset local Sovereign Chain +### Stop and clean local Sovereign Chain -1. Navigate to `/mx-chain-go/scripts/testnet/sovereignBridge`. +1. Navigate to `mx-chain-go/scripts/testnet/sovereignBridge`. Source the script: ```bash source script.sh ``` -2. Upgrade and reset Sovereign chain and all dependent services: +2. Stop and clean the chain with all dependent services: ```bash - sovereignUpgradeAndReset + stopAndCleanSovereign ``` -## Restart local Sovereign Chain +### Upgrade and reset local Sovereign Chain -1. Navigate to `/mx-chain-go/scripts/testnet/sovereignBridge`. +1. Navigate to `mx-chain-go/scripts/testnet/sovereignBridge`. Source the script: ```bash source script.sh ``` -3. Restart Sovereign chain and all dependent services: +2. Upgrade and reset Sovereign chain and all dependent services: ```bash - sovereignRestart + sovereignUpgradeAndReset ``` - -:::important -This version of the documentation focuses solely on the essential steps required to set up and deploy a sovereign chain on either a local or remote computer. It does not include instructions for configuring: - -- Round length -- Gas token -- Fee model -- Consensus model -- And other related settings -::: - diff --git a/docs/sovereign/one-click-setup.md b/docs/sovereign/one-click-setup.md new file mode 100644 index 000000000..6d2eb1f12 --- /dev/null +++ b/docs/sovereign/one-click-setup.md @@ -0,0 +1,13 @@ +# One-click deploy Setup Guide + +## One-click local sovereign deployment in Digital Ocean + +Currently, the only solution for one-click deployment we have is available in Digital Ocean marketplace. This solution will create a droplet for with a local sovereign chain connected to MultiversX public testnet, including all necessary services like API, wallet, explorer and others. + +### Create sovereign chain droplet + +- Go to [Digital Ocean marketplace](https://marketplace.digitalocean.com/apps/multiversx-testnet-sovereign-chain) and create your Sovereign Chain droplet. + +:::note +It is recommended to choose a droplet with minimum 8 CPUs and 32GB RAM for the best performance. +::: diff --git a/docs/sovereign/sovereign-api.md b/docs/sovereign/sovereign-api.md new file mode 100644 index 000000000..7a4c7d1bb --- /dev/null +++ b/docs/sovereign/sovereign-api.md @@ -0,0 +1,55 @@ +# API service + +## Deploy Sovereign API service + +### Step 1: Get the `mx-api-service` Repository + +1. Clone the GitHub repository: + ```bash + git clone https://github.com/multiversx/mx-api-service.git + ``` + +2. Checkout the sovereign branch and navigate to testnet directory: + ```bash + cd mx-api-service && git fetch && git checkout feat/sovereign + ``` + +### Step 2: Edit API config + +1. Navigate to the `config` folder: + ```bash + cd config + ``` + +2. Update the configuration files (we are starting from testnet configuration in this example): + - config.testnet.yaml` - enable/disable the services you need + - `dapp.config.testnet.json` + +### Step 3: Start Sovereign API service + +```bash +npm run start:testnet +``` + +## Deploy Sovereign Extras service + +The extras service only includes the `faucet` option at the moment. + +### Step 1: Get the ```mx-lite-extras-service``` Repository + +```bash +git clone https://github.com/multiversx/mx-lite-extras-service.git +``` + +### Step 2: Update extras configuration files + +- `.env.custom` - change `API_URL` and `GATEWAY_URL` with your own URLs +- `config/config.yaml` - update the faucet configuration parameters as needed + +### Step 3: Start Sovereign Extras service + +```bash +NODE_ENV=custom npm run start:faucet +``` + +Read more about deploying API service in [GitHub](https://github.com/multiversx/mx-lite-extras-service#quick-start). diff --git a/docs/sovereign/sovereign-explorer.md b/docs/sovereign/sovereign-explorer.md new file mode 100644 index 000000000..6f4111f55 --- /dev/null +++ b/docs/sovereign/sovereign-explorer.md @@ -0,0 +1,27 @@ +# Explorer service + +## Deploy Explorer + +### Step 1: Get the `mx-explorer-dapp` Repository + +```bash +git clone https://github.com/multiversx/mx-explorer-dapp.git +``` + +### Step 2: Update explorer configuration file + +1. Navigate to the `src/config` folder: + ```bash + cd src/config + ``` + +2. Update the parameters and URLs with your own configuration in `config.testnet.ts` file + +### Step 3: Start Sovereign Explorer + +```bash +yarn +npm run start-testnet +``` + +Read more about deploying explorer in [GitHub](https://github.com/multiversx/mx-explorer-dapp/tree/main#quick-start). diff --git a/docs/sovereign/sovereign-wallet.md b/docs/sovereign/sovereign-wallet.md new file mode 100644 index 000000000..13aa3c1dd --- /dev/null +++ b/docs/sovereign/sovereign-wallet.md @@ -0,0 +1,32 @@ +# Wallet service + +## Deploy Lite Wallet + +### Step 1: Get the `mx-lite-wallet-dapp` Repository + +```bash +git clone https://github.com/multiversx/mx-lite-wallet-dapp.git +``` + +### Step 2: Update sovereign configuration file + +1. Navigate to the `src/config` folder: + ```bash + cd src/config + ``` + +2. Update the `config.sovereign.ts` file: + - for `sovereign` item + - update the URLs with your own + - update `sovereignContractAddress` with contract address from `sovereignConfig.toml` -> `SubscribedEvents` from `OutgoingSubscribedEvents` + - for `testnet` item (or the network your sovereign is connected to) + - update `sovereignContractAddress` with contract address from `sovereignConfig.toml` -> `SubscribedEvents` from `NotifierConfig` + +### Step 3: Start Sovereign Lite Wallet + +```bash +yarn install +yarn start:sovereign +``` + +Read more about deploying lite wallet in [GitHub](https://github.com/multiversx/mx-lite-wallet-dapp/tree/main#multiversx-lite-wallet-dapp). diff --git a/sidebars.js b/sidebars.js index 00d738954..d48fa7c26 100644 --- a/sidebars.js +++ b/sidebars.js @@ -541,8 +541,23 @@ const sidebars = { "sovereign/system-requirements", "sovereign/software-dependencies",], }, - "sovereign/setup", - "sovereign/deployment", + { + type: "category", + label: "Setup Guide", + items: [ + "sovereign/one-click-setup", + "sovereign/local-setup", + "sovereign/distributed-setup",], + }, + "sovereign/custom-configurations", + { + type: "category", + label: "Services", + items: [ + "sovereign/sovereign-api", + "sovereign/sovereign-wallet", + "sovereign/sovereign-explorer",], + }, { type: "category", label: "Managing a Sovereign Chain", From 678418182fbe52a5099b6818b45bf6af8c58fb7c Mon Sep 17 00:00:00 2001 From: axenteoctavian Date: Wed, 15 Jan 2025 14:35:05 +0200 Subject: [PATCH 2/3] updates after review --- docs/sovereign/custom-configurations.md | 8 +- docs/sovereign/distributed-setup.md | 103 +++++++++++++----------- docs/sovereign/local-setup.md | 93 ++++++++++----------- docs/sovereign/one-click-deployment.md | 17 ++++ docs/sovereign/one-click-setup.md | 13 --- docs/sovereign/services.md | 40 +++++++++ docs/sovereign/sovereign-api.md | 4 +- sidebars.js | 3 +- 8 files changed, 173 insertions(+), 108 deletions(-) create mode 100644 docs/sovereign/one-click-deployment.md delete mode 100644 docs/sovereign/one-click-setup.md create mode 100644 docs/sovereign/services.md diff --git a/docs/sovereign/custom-configurations.md b/docs/sovereign/custom-configurations.md index ceba5e916..02a807fd9 100644 --- a/docs/sovereign/custom-configurations.md +++ b/docs/sovereign/custom-configurations.md @@ -27,12 +27,16 @@ The Sovereign Chain SDK is built with flexibility in mind, allowing you to tailo ### sovereignConfig.toml -- `GenesisConfig.NativeESDT` - Native ESDT identifier for the sovereign chain +- `GenesisConfig.NativeESDT` - Native ESDT identifier for the Sovereign Chain ### prefs.toml The `OverridableConfigTomlValues` will overwrite the parameters in the config files. Make sure that your new config parameters are not overwritten by this file. :::note -These are just a few examples that you can adjust to make the sovereign chain unique. All the files you could adjust when creating a sovereign chain can be found in the [deployment guide](/sovereign/distributed-setup#step-4-edit-the-sovereign-configuration). +These are just a few examples that you can adjust to make the Sovereign Chain unique. All the files you could adjust when creating a Sovereign Chain can be found in the [deployment guide](/sovereign/distributed-setup#step-4-edit-the-sovereign-configuration). +::: + +:::note +We will continue to add configurations for features such as token-less chains, gas-less chains, and other customizations at a later stage, following their implementation. ::: diff --git a/docs/sovereign/distributed-setup.md b/docs/sovereign/distributed-setup.md index 2f1491a95..28b2493d7 100644 --- a/docs/sovereign/distributed-setup.md +++ b/docs/sovereign/distributed-setup.md @@ -1,8 +1,8 @@ -# Distributed Setup Guide +# Distributed Setup -## Deploy distributed Sovereign Chain +## Create distributed Sovereign Chain configuration -This guide will help you deploy a public Sovereign Chain with real validators. +This guide will help you deploy a public Sovereign Chain with real validators, enabling a truly decentralized setup. At its core, blockchain technology—and Sovereign Chains in particular—are designed to operate in a decentralized manner, powered by multiple independent validators. This ensures transparency, security, and resilience, as no single entity has control over the entire system. Unlike other guides we’ve provided, which focus on local setups, this solution emphasizes decentralization by involving multiple stakeholders in the validation process. By following the steps below, the owner can create the Sovereign Chain configuration for the network: ### Step 1: Get the ```mx-chain-go``` Repository @@ -13,14 +13,14 @@ Before proceeding, ensure that a **SSH key** for GitHub is configured on your ma git clone git@github.com:multiversx/mx-chain-go.git ``` -2. Checkout the specific sovereign chain sdk branch and navigate to testnet directory: +2. Checkout the specific Sovereign Chain SDK branch and navigate to testnet directory: ```bash - cd mx-chain-go && git fetch && git checkout d699ffd6a29513c573b1d212861f932e037d8f67 && cd scripts/testnet + cd mx-chain-go && git fetch && git checkout d699ffd && cd scripts/testnet ``` -:::info -`d699ffd6a29513c573b1d212861f932e037d8f67` is the commit hash we recommend to be used. If you want to use the latest version you can use the branch `feat/chain-go-sdk`. -::: + :::info + `d699ffd` is the commit hash we recommend to be used. If you want to use the latest version you can use the branch `feat/chain-go-sdk`. + ::: ### Step 2: Seeder Build @@ -31,18 +31,22 @@ go build ./seednode -rest-api-interface 127.0.0.1:9091 -log-level *:DEBUG -log-save ``` -The output will be something like this. The highlighted part is important and will be used later. +You should have an output similar to the one displayed below. The highlighted part is important and will be used later. -| Seednode addresses: | +| Seednode addresses: | |---------------------------------------------------------------------------------------------| | `/ip4/`127.0.0.1`/tcp/10000/p2p/16Uiu2HAmSY5NpuqC8UuFHunJensFbBc632zWnMPCYfM2wNLuvAvL` | | `/ip4/`192.168.10.100`/tcp/10000/p2p/16Uiu2HAmSY5NpuqC8UuFHunJensFbBc632zWnMPCYfM2wNLuvAvL` | +:::info +All the validator nodes will have to connect to this seed node. +::: ### Step 3: Sovereign node build Build the sovereign node ```bash +cd .. cd cmd/sovereignnode/ go build -v -ldflags="-X main.appVersion=v0.0.1" ``` @@ -53,31 +57,35 @@ Use your own custom version instead of `v0.0.1`. ### Step 4: Edit the sovereign configuration -Node configs and be found in `cmd/node/config`. Below are the files and folders: -- gasSchedules folder -- genesisContracts folder -- genesis.json* -- genesisSmartContracts.json -- nodesSetup.json* -- api.toml -- config.toml -- economics.toml -- enableEpochs.toml -- enableRounds.toml -- external.toml -- fullArchiveP2P.toml -- p2p.toml -- prefs.toml -- ratings.toml -- systemSmartContractsConfig.toml +Node configs can be found in `cmd/node/config`. Below are the files and folders: +``` +gasSchedules folder +genesisContracts folder +genesis.json* +genesisSmartContracts.json +nodesSetup.json* +api.toml +config.toml +economics.toml +enableEpochs.toml +enableRounds.toml +external.toml +fullArchiveP2P.toml +p2p.toml +prefs.toml +ratings.toml +systemSmartContractsConfig.toml +``` _Note: Files marked with * will be discussed later in the document._ Sovereign configs can be found in `cmd/sovereignnode/config` -- economics.toml -- enableEpochs.toml -- prefs.toml -- sovereignConfig.toml +``` +economics.toml +enableEpochs.toml +prefs.toml +sovereignConfig.toml +``` #### Minimum recommended changes @@ -88,18 +96,18 @@ Sovereign configs can be found in `cmd/sovereignnode/config` 2. EpochStartConfig.RoundsPerEpoch 2. **p2p.toml** 1. KadDhtPeerDiscovery:InitialPeerList = `[/ip4/PUBLIC_IP/tcp/10000/p2p/16Uiu2HAmSY5NpuqC8UuFHunJensFbBc632zWnMPCYfM2wNLuvAvL]` - - PUBLIC_IP is the IP of the machine where seed node is running, the other part is from seed node build + - PUBLIC_IP is the IP of the machine where seed node is running, the other part is seed node address 3. **systemSmartContractsConfig.toml** 1. ESDTSystemSCConfig.ESDTPrefix 2. StakingSystemSCConfig.NodeLimitPercentage [[docs](https://docs.multiversx.com/validators/staking-v4/#how-does-the-dynamic-node-limitation-work)] 4. **sovereignConfig.toml** 1. GenesisConfig.NativeESDT 3. Other changes: - - Use the [custom configuration](/sovereign/deployment) page to see more configs we recommend to be changed + - Use the [custom configuration](/sovereign/custom-configurations) page to see more configs we recommend to be changed ### Step 5: Genesis configuration -#### **genesis.json** +#### `genesis.json` This file should contain all the genesis addresses that will be funded and will be validators. Adjust as needed. @@ -133,7 +141,7 @@ Example with 2 validators: ] ``` -#### **nodesSetup.json** +#### `nodesSetup.json` This file contains all the initial nodes. Adjust as needed. @@ -173,28 +181,29 @@ Example: ___ -At this point, a `config` folder should be created that will contain all the .toml files and genesis configuration. +:::note +At this point, a `config` folder should be created that will contain all the .toml files and genesis configuration. This folder should be shared with the other validators so they will be able to join the network. +::: -### Step 6: Validators setup +## Join a Sovereign Chain as validator/observer -#### Sovereign validator setup +### Sovereign validator setup Each validator should have: -- **walletKey.pem** - wallet that will be funded at genesis -- **validatorKey.pem** (or **allValidatorsKey.pem** if multisig node) - validator pem used to deploy the node -- **config** folder +- **walletKey.pem** - wallet that will be funded at genesis [[docs](/validators/key-management/wallet-keys)] +- **validatorKey.pem** (or **allValidatorsKey.pem** if multi key node) - validator key [[docs](/validators/key-management/validator-keys/#how-to-generate-a-new-key)] +- **config** folder - received from Sovereign Chain creator -#### Sovereign validator/observer node start +### Sovereign validator/observer node start The following commands will start the sovereign validator node with the configuration from **config** folder and with the **validatorKey** (or multi key from **allValidatorsKey**). Adjust the flags as needed. You can find all the available flags in `/mx-chain-go/cmd/sovereignnode/flags.go` -#### #single key +#### # single key ``` ./sovereignnode --validator-key-pem-file ./config/validatorKey.pem --profile-mode --log-save --log-level *:INFO --log-logger-name --log-correlation --use-health-service --rest-api-interface :8080 --working-directory ~/my_validator_node ``` - #### # multi key ``` ./sovereignnode --all-validator-keys-pem-file ./config/allValidatorsKey.pem --profile-mode --log-save --log-level *:INFO --log-logger-name --log-correlation --use-health-service --rest-api-interface :8080 --working-directory ~/my_validator_node @@ -205,6 +214,10 @@ Adjust the flags as needed. You can find all the available flags in `/mx-chain-g ./sovereignnode --profile-mode --log-save --log-level *:INFO --log-logger-name --log-correlation --use-health-service --rest-api-interface :8080 --working-directory ~/my_observer_node ``` +### Staking transaction + +Before staking, a node is a mere observer. After staking, the node becomes a validator, which means that it will be eligible for consensus and will earn rewards. You can find the documentation how to make the staking transaction with mxpy [here](/validators/staking#staking-through-mxpy). + ## Deploy services -You can find the documentation on how to deploy services at [this link](/sovereign/sovereign-api). +You can find the documentation on how to deploy services [here](/sovereign/services). diff --git a/docs/sovereign/local-setup.md b/docs/sovereign/local-setup.md index fce7fc1c5..fc6cb6309 100644 --- a/docs/sovereign/local-setup.md +++ b/docs/sovereign/local-setup.md @@ -1,4 +1,4 @@ -# Full Local Setup Guide +# Full Local Setup ## Deploy local Sovereign Chain @@ -13,52 +13,57 @@ Before proceeding, ensure that a **SSH key** for GitHub is configured on your ma git clone git@github.com:multiversx/mx-chain-go.git ``` -2. Checkout the specific sovereign chain sdk branch and navigate to testnet directory: +2. Checkout the specific Sovereign Chain SDK branch and navigate to testnet directory: ```bash cd mx-chain-go && git fetch && git checkout d699ffd6a29513c573b1d212861f932e037d8f67 && cd scripts/testnet ``` -:::info -`d699ffd6a29513c573b1d212861f932e037d8f67` is the commit hash we recommend to be used. If you want to use the latest version you can use the branch `feat/chain-go-sdk`. -::: + :::info + `d699ffd6a29513c573b1d212861f932e037d8f67` is the commit hash we recommend to be used. If you want to use the latest version you can use the branch `feat/chain-go-sdk`. + ::: 3. Run the prerequisites script: ```bash ./prerequisites.sh ``` -:::info -The prerequisites script verifies and downloads the necessary packages to run the nodes and clones the required repositories: + :::info + The prerequisites script verifies and downloads the necessary packages to run the nodes and clones the required repositories: -- **mx-chain-deploy-go**: Initializes the configuration for the chain and deployment parameters. -- **mx-chain-proxy-go**: Repository for the proxy. -- **mx-chain-sovereign-bridge-go**: Repository for the cross-chain service. -::: + - **mx-chain-deploy-go**: Initializes the configuration for the chain and deployment parameters. + - **mx-chain-proxy-go**: Repository for the proxy. + - **mx-chain-sovereign-bridge-go**: Repository for the cross-chain service. + - **mx-chain-tools-go**: Repository for updating elastic indices. + ::: ### Step 2: Deploy Sovereign setup -1. Navigate to the `sovereignBridge` folder: - ```bash - cd sovereignBridge - ``` +Navigate to the `sovereignBridge` folder: +```bash +cd sovereignBridge +``` -2. Install the [software dependencies](/sovereign/software-dependencies) and download the cross-chain contracts by running the sovereign bridge prerequisites script: +1. Install the [software dependencies](/sovereign/software-dependencies) and download the cross-chain contracts by running the sovereign bridge prerequisites script: ```bash ./prerequisites.sh ``` -3. Create a new wallet: +2. Create a new wallet: ```bash mxpy wallet new --format pem --outfile ~/wallet.pem ``` -:::note -You can use any wallet of your choice, but for the purpose of this guide we are generating a new wallet. -::: + :::info + This wallet is the owner for cross chain smart contracts and is used by the sovereign bridge service. + ::: + + :::note + You can use any wallet of your choice, but for the purpose of this guide we are generating a new wallet. + ::: -3. Get funds in the wallet on the chain you want the sovereign to be connected to. +3. Get funds in this wallet on the chain (testnet/devnet/mainnet) you want the sovereign to be connected to. -4. Update the configuration file `config/configs.cfg` with paths you want to use, wallet location and main chain constants. Example: +4. Update the configuration file `config/configs.cfg` with paths you want to use, wallet location and main chain constants. The following example shows the paths you have to use in order to connect to public MultiversX testnet: ``` # Sovereign Paths SOVEREIGN_DIRECTORY="~/sovereign" @@ -73,63 +78,61 @@ You can use any wallet of your choice, but for the purpose of this guide we are CHAIN_ID = T ``` -:::note -- **SOVEREIGN_DIRECTORY, TXS_OUTFILE_DIRECTORY, CONTRACTS_DIRECTORY** - represent the paths to the location where the deploy scripts will generate the outputs. -- **WALLET** - should represent the wallet generated at Step 1. -- **PROXY** - in this case, for the purpose of the test, the used proxy is the testnet one. Of course that the proper proxy should be used when deploying your own set of contracts depending on the development phase of your project. -- **CHAIN_ID** - should represent the chain ID of the chain where the contracts are to be deployed. - - **"1"** for Mainnet; - - **"D"** for Devnet; - - **"T"** for Testnet; - - or use you own local network ID -::: + :::note + - **SOVEREIGN_DIRECTORY, TXS_OUTFILE_DIRECTORY, CONTRACTS_DIRECTORY** - represent the paths to the location where the deployment scripts will generate the outputs. + - **WALLET** - should represent the wallet generated at Step 2.2. + - **PROXY** - in this case, for the purpose of the test, the used proxy is the testnet one. Of course that the proper proxy should be used when deploying your own set of contracts depending on the development phase of your project. + - **CHAIN_ID** - should represent the chain ID of the chain where the contracts are to be deployed. + - **"1"** for Mainnet; + - **"D"** for Devnet; + - **"T"** for Testnet; + - or use you own local network ID + ::: 5. Source the script: ```bash source script.sh ``` -6. Deploy all cross-chain contracts on main chain and deploy sovereign chain with all dependent services: +6. Deploy all cross-chain contracts on main chain and deploy Sovereign Chain with all required services: ```bash deploySovereignWithCrossChainContracts ``` -:::info -`deploySovereignWithCrossChainContracts` command will: -- deploy all main chain smart contracts and update sovereign configs -- deploy sovereign nodes and the main chain observer -::: + :::info + `deploySovereignWithCrossChainContracts` command will: + - deploy all main chain smart contracts and update sovereign configs + - deploy sovereign nodes and the main chain observer + ::: ### Step 3: Deploy services -You can find the documentation on how to deploy services [here](/sovereign/sovereign-api). +You can find the documentation on how to deploy services [here](/sovereign/services). ___ -### Stop and clean local Sovereign Chain +## Stop and clean local Sovereign Chain 1. Navigate to `mx-chain-go/scripts/testnet/sovereignBridge`. - Source the script: ```bash source script.sh ``` -2. Stop and clean the chain with all dependent services: +2. Stop and clean the chain, and all sovereign services: ```bash stopAndCleanSovereign ``` -### Upgrade and reset local Sovereign Chain +## Upgrade and reset local Sovereign Chain 1. Navigate to `mx-chain-go/scripts/testnet/sovereignBridge`. - Source the script: ```bash source script.sh ``` -2. Upgrade and reset Sovereign chain and all dependent services: +2. Upgrade and reset the chain, and all sovereign services: ```bash sovereignUpgradeAndReset ``` diff --git a/docs/sovereign/one-click-deployment.md b/docs/sovereign/one-click-deployment.md new file mode 100644 index 000000000..3f58bb35d --- /dev/null +++ b/docs/sovereign/one-click-deployment.md @@ -0,0 +1,17 @@ +# One-Click Deployment + +## One-click local sovereign deployment in Digital Ocean + +At present, the only one-click deployment solution we offer is available on the Digital Ocean marketplace. This solution sets up a droplet containing a local Sovereign Chain connected to the MultiversX public testnet, complete with all essential services such as API, wallet, explorer, and more. + +### Create Sovereign Chain droplet + +- Go to [Digital Ocean marketplace](https://marketplace.digitalocean.com/apps/multiversx-testnet-sovereign-chain) for more info and to create your Sovereign Chain droplet. + +:::note +It is recommended to choose a droplet with minimum 8 CPUs and 32GB RAM for the best performance. +::: + +:::important +The one-click deployment setup provided in this guide is designed primarily for development purposes. By default, it connects to the MultiversX public testnet and runs all services on the same machine. This setup is equivalent to the Full Local Setup but operates in the cloud, providing a convenient way to test and develop your Sovereign Chain in a hosted environment. +::: diff --git a/docs/sovereign/one-click-setup.md b/docs/sovereign/one-click-setup.md deleted file mode 100644 index 6d2eb1f12..000000000 --- a/docs/sovereign/one-click-setup.md +++ /dev/null @@ -1,13 +0,0 @@ -# One-click deploy Setup Guide - -## One-click local sovereign deployment in Digital Ocean - -Currently, the only solution for one-click deployment we have is available in Digital Ocean marketplace. This solution will create a droplet for with a local sovereign chain connected to MultiversX public testnet, including all necessary services like API, wallet, explorer and others. - -### Create sovereign chain droplet - -- Go to [Digital Ocean marketplace](https://marketplace.digitalocean.com/apps/multiversx-testnet-sovereign-chain) and create your Sovereign Chain droplet. - -:::note -It is recommended to choose a droplet with minimum 8 CPUs and 32GB RAM for the best performance. -::: diff --git a/docs/sovereign/services.md b/docs/sovereign/services.md new file mode 100644 index 000000000..08c69c48a --- /dev/null +++ b/docs/sovereign/services.md @@ -0,0 +1,40 @@ +# Introduction + +## Sovereign services + +### API service + +The Sovereign API is a wrapper over the Sovereign Proxy that brings a robust caching mechanism, alongside Elasticsearch historical queries support, tokens media support, delegation & staking data, and many others. + +### Lite Extras API +The Sovereign Lite Extras API includes a faucet service that allows users to obtain test tokens for their wallet. + +### Lite Wallet +The Sovereign Lite Wallet is a lightweight version of the public wallet. It supports key functionalities such as cross-chain transfers, token issuance, token transfers, and more. + +### Explorer DApp +The Explorer DApp serves as the blockchain explorer for the Sovereign Chain, providing insights into transactions, blocks, and other on-chain activity. + +## Software dependencies + +### Node.js + +[Download Node.js](https://nodejs.org/en/download) or use a version manager like [NVM](https://github.com/nvm-sh/nvm) + +### Yarn + +To install yarn, use the following command: +```bash +npm install --global yarn +``` + +### Redis + +To install and start redis, use the following commands: + +```bash +sudo apt update +sudo apt install redis +sudo systemctl start redis +sudo systemctl enable redis +``` diff --git a/docs/sovereign/sovereign-api.md b/docs/sovereign/sovereign-api.md index 7a4c7d1bb..684305937 100644 --- a/docs/sovereign/sovereign-api.md +++ b/docs/sovereign/sovereign-api.md @@ -22,8 +22,8 @@ ``` 2. Update the configuration files (we are starting from testnet configuration in this example): - - config.testnet.yaml` - enable/disable the services you need - - `dapp.config.testnet.json` + - `config.testnet.yaml` - enable/disable or configure the services you need + - `dapp.config.testnet.json` - dapp configuration file ### Step 3: Start Sovereign API service diff --git a/sidebars.js b/sidebars.js index d48fa7c26..60fe74d1d 100644 --- a/sidebars.js +++ b/sidebars.js @@ -545,7 +545,7 @@ const sidebars = { type: "category", label: "Setup Guide", items: [ - "sovereign/one-click-setup", + "sovereign/one-click-deployment", "sovereign/local-setup", "sovereign/distributed-setup",], }, @@ -554,6 +554,7 @@ const sidebars = { type: "category", label: "Services", items: [ + "sovereign/services", "sovereign/sovereign-api", "sovereign/sovereign-wallet", "sovereign/sovereign-explorer",], From ee15bb60fddfa255e39c4c10ba4910c405f6052d Mon Sep 17 00:00:00 2001 From: axenteoctavian Date: Wed, 15 Jan 2025 18:04:42 +0200 Subject: [PATCH 3/3] updates after review --- docs/sovereign/one-click-deployment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sovereign/one-click-deployment.md b/docs/sovereign/one-click-deployment.md index 3f58bb35d..623ae75d3 100644 --- a/docs/sovereign/one-click-deployment.md +++ b/docs/sovereign/one-click-deployment.md @@ -2,7 +2,7 @@ ## One-click local sovereign deployment in Digital Ocean -At present, the only one-click deployment solution we offer is available on the Digital Ocean marketplace. This solution sets up a droplet containing a local Sovereign Chain connected to the MultiversX public testnet, complete with all essential services such as API, wallet, explorer, and more. +At present, the only one-click deployment option is available on the Digital Ocean marketplace. This solution sets up a droplet containing a local Sovereign Chain connected to the MultiversX public testnet, complete with all essential services such as API, wallet, explorer, and more. ### Create Sovereign Chain droplet