diff --git a/astro.config.js b/astro.config.js index 132946e8..5656b72e 100644 --- a/astro.config.js +++ b/astro.config.js @@ -19,6 +19,8 @@ export default defineConfig({ '/itn/node-running-guide': '/nocturne/node-running-guide', '/itn/testnet-faucet': '/nocturne/testnet-faucet', '/itn/upgrade-node': '/nocturne/upgrade-node', + '/operator/guides/archive-node': '/operator/archive-node', + '/operator/guides/provisioner-node': '/operator/provisioner', }, integrations: [ starlight({ diff --git a/src/content/docs/developer/integrations/exchanges.md b/src/content/docs/developer/integrations/exchanges.md index b147433b..0d7f1514 100644 --- a/src/content/docs/developer/integrations/exchanges.md +++ b/src/content/docs/developer/integrations/exchanges.md @@ -18,7 +18,7 @@ To access the blockchain you can either: You can interact with the blockchain and submit transactions by operating a Dusk node. -To set up a node, you may choose to use the [node installer](/operator/guides/provisioner-node/#node-installer) or manually install Rusk by following the provided [installation instructions](/operator/installation). +To set up a node, you may choose to use the [node installer](/operator/provisioner#node-installer) (recommended) or manually install Rusk by following the provided [installation instructions](https://github.com/dusk-network/rusk/blob/master/INSTALLATION.md). Requirements vary depending on whether you are configuring a [Provisioner](/operator/provisioner) node or an [Archive](/operator/archive-node) node. diff --git a/src/content/docs/developer/smart-contract/guides/testing.md b/src/content/docs/developer/smart-contract/guides/testing.md index 36810b1d..de758a85 100644 --- a/src/content/docs/developer/smart-contract/guides/testing.md +++ b/src/content/docs/developer/smart-contract/guides/testing.md @@ -18,7 +18,7 @@ An example for integration testing can be seen in the tests folder of our genesi ### Testing on Nocturne -Testing on Nocturne requires you to deploy the smart contract to the Nocturne chain and call the functions there via transactions. To get nDusk for the testnet you can use the [Faucet](/operator/guides/nocturne-faucet). +Testing on Nocturne requires you to deploy the smart contract to the Nocturne chain and call the functions there via transactions. To get nDusk for the testnet you can use the [Faucet](/operator/networks#how-to-get-testnet-tokens). ## Additional Resources diff --git a/src/content/docs/learn/community.mdx b/src/content/docs/learn/community.mdx index 3cc27f9b..8fb82753 100644 --- a/src/content/docs/learn/community.mdx +++ b/src/content/docs/learn/community.mdx @@ -34,4 +34,4 @@ Your feedback helps us improve. Feel free to suggest new ideas or report any iss ## Join Dusk as a Node operator -To ease you into the intricacies of Dusk, you might consider participating in node running: [run a Provisioner node](/operator/guides/provisioner-node). +To ease you into the intricacies of Dusk, you might consider participating in node running: [run a Provisioner node](/operator/provisioner). diff --git a/src/content/docs/learn/guides/duskevm-bridge.md b/src/content/docs/learn/guides/duskevm-bridge.md index 96fefdf3..3f8fe846 100644 --- a/src/content/docs/learn/guides/duskevm-bridge.md +++ b/src/content/docs/learn/guides/duskevm-bridge.md @@ -3,22 +3,22 @@ title: Bridge DUSK from DuskDS to DuskEVM Testnet description: How to use the Dusk Web Wallet to move DUSK from the DuskDS testnet to the DuskEVM testnet and interact with the EVM network. --- -This guide explains how to bridge your DUSK on DuskDS to DuskEVM on the public testnet using the official Dusk Web Wallet +This guide explains how to bridge your DUSK on DuskDS to DuskEVM on the public testnet using the official Dusk Web Wallet. -Once bridged, your DUSK becomes the native gas token on DuskEVM, so you can deploy and interact with smart contracts using standard EVM tooling. +Once bridged, your DUSK becomes the native gas token on DuskEVM, so you can deploy and interact with smart contracts using standard EVM tooling. ## 1) Prerequisites Before you start, make sure you have: -- A Dusk Web Wallet account and some testnet DUSK. For more details on getting testnet DUSK see the [Nocturne Faucet Guide](/operator/guides/nocturne-faucet/). +- A Dusk Web Wallet account and some testnet DUSK. For more details on getting testnet DUSK see the [Nocturne Faucet Guide](/operator/networks#how-to-get-testnet-tokens). - Make sure to have the amount of DUSK unshielded you want to bridge. - A Web3 wallet (e.g. MetaMask) installed in your browser. -- Optional, for developers: familiarity with the [DuskEVM deep dive](/learn/deep-dive/dusk-evm/) and [Deploy on DuskEVM](/developer/smart-contracts-dusk-evm/deploy-on-evm/). +- Optional, for developers: familiarity with the [DuskEVM deep dive](/learn/deep-dive/dusk-evm/) and [Deploy on DuskEVM](/developer/smart-contracts-dusk-evm/deploy-on-evm/). ## 2) Open the Web Wallet on DuskDS testnet -1. Visit the [Dusk Web Wallet](https://apps.testnet.dusk.network/wallet/) +1. Visit the [Dusk Web Wallet](https://apps.testnet.dusk.network/wallet/) 2. Unlock your wallet (or restore it with your 12‑word recovery phrase if needed). 3. Confirm you have enough unshielded DUSK. You need enough for the amount you want to bridge and a small bridge fee. @@ -88,7 +88,7 @@ Carefully verify: If everything looks good: 1. Click SEND. -2. The wizard moves to Step 3 (status screen). +2. The wizard moves to Step 3 (status screen). You’ll see status messages such as "Processing transaction" and "Transaction pending", and a "VIEW ON BLOCK EXPLORER" button for the originating transaction. Under the hood, the wallet creates and broadcasts a DuskDS transaction that calls the bridge contract’s `deposit` function with your amount. This locks DUSK on DuskDS and schedules minting on DuskEVM for your EVM address. @@ -97,7 +97,7 @@ Under the hood, the wallet creates and broadcasts a DuskDS transaction that call ### 6.1 On DuskDS -When the DuskDS transaction is created the status screen in the bridge wizard shows your transaction as **pending**. The "VIEW ON BLOCK EXPLORER" button opens the Dusk block explorer, where you can inspect the transaction status, fees and gas used. +When the DuskDS transaction is created the status screen in the bridge wizard shows your transaction as **pending**. The "VIEW ON BLOCK EXPLORER" button opens the Dusk block explorer, where you can inspect the transaction status, fees and gas used. You can also manually go to the [DuskDS Testnet Explorer](https://apps.testnet.dusk.network/explorer/) and search by your DuskDS address or the transaction hash. @@ -107,11 +107,11 @@ Once the deposit has been processed by DuskEVM, which can take a couple of minut To inspect this on the explorer: -1. Open the [DuskEVM testnet explorer](https://explorer.testnet.evm.dusk.network/). +1. Open the [DuskEVM testnet explorer](https://explorer.testnet.evm.dusk.network/). 2. Search by your EVM address. 3. You’ll see standard EVM‑style transaction details: Block number, gas used, logs, etc. -Because DuskEVM is an EVM‑equivalent environment, the explorer behaves much like other EVM explorers. +Because DuskEVM is an EVM‑equivalent environment, the explorer behaves much like other EVM explorers. ## 7) Interacting with DuskEVM after bridging @@ -127,11 +127,11 @@ Once you have DUSK on DuskEVM Testnet, you can use it just like gas on any EVM c For developers: -1. Configure your tooling (Hardhat, Foundry, etc.) to talk to the DuskEVM testnet RPC endpoint and chain ID. These details are available on the [Deploy on DuskEVM](/developer/smart-contracts-dusk-evm/deploy-on-evm/) guide. +1. Configure your tooling (Hardhat, Foundry, etc.) to talk to the DuskEVM testnet RPC endpoint and chain ID. These details are available on the [Deploy on DuskEVM](/developer/smart-contracts-dusk-evm/deploy-on-evm/) guide. 2. Use the same EVM address you funded via the bridge as the deployer: - Hardhat: set the private key of that account in your network config. - Foundry: use the same account for `forge create` / `cast` commands. -3. Gas costs and transaction semantics follow the EVM‑equivalent rules described in the [DuskEVM overview](/learn/deep-dive/dusk-evm/). +3. Gas costs and transaction semantics follow the EVM‑equivalent rules described in the [DuskEVM overview](/learn/deep-dive/dusk-evm/). Because DuskEVM is EVM‑equivalent and built on the OP Stack, most Ethereum tooling works out of the box — you only need to point it to the correct RPC and chain ID. @@ -161,4 +161,4 @@ After you submit a withdrawal: - On the DuskDS side, the withdrawal becomes finalizable after a certain number of blocks (the finalization period). - The Web Wallet’s Bridge -> Transactions view shows your pending withdrawals: - Once a withdrawal is ready, a "Finalize now" button appears. - - Clicking it sends a DuskDS transaction to finalize the withdrawal and release your DUSK back to your DuskDS account, this can take up to 15 minutes. + - Clicking it sends a DuskDS transaction to finalize the withdrawal and release your DUSK back to your DuskDS account, this can take up to 15 minutes. diff --git a/src/content/docs/operator/FAQ.md b/src/content/docs/operator/FAQ.md index b314b1fc..35c113e8 100644 --- a/src/content/docs/operator/FAQ.md +++ b/src/content/docs/operator/FAQ.md @@ -14,7 +14,8 @@ description: Frequently asked questions about running a node on Dusk. The full node that is used to take part in the consensus is the [**provisioner node**](/operator/provisioner). #### Can I build Rusk from source? -Yes, instructions to build Rusk from source can be found [here](/operator/from-source) + +Yes, instructions to build Rusk from source can be found [here](https://github.com/dusk-network/rusk/blob/master/INSTALLATION.md) #### Which ports does Dusk use? @@ -85,8 +86,9 @@ As there's also a password on the file when you export, you need to set it on th As long as you have your mnemonic phrase stored safely, you can recover everything else. #### What should I do if I lose my SSH key file? -1) Spin up a fresh instance and [install Rusk](/operator/installation) -2) Restore your wallet using the previous mnemonic. + +1) Spin up a fresh instance and [install Rusk](/operator/provisioner) +2) Restore your wallet using the previous mnemonic. 3) [Export the consensus key](/operator/guides/node-wallet-setup/#export-consensus-key) from the restored wallet. 4) Once the new node is fully synced, it will start participating in consensus. There is no need to stake again. You can then safely delete the old instance. @@ -102,7 +104,7 @@ rusk-wallet moonlight-stake --amt 3000 ``` #### How to resume validating again after missing an upgrade? -If you didn't upgrade your node on time and got soft slashed, you need to: +If you didn't upgrade your node on time and got soft slashed, you need to: 1) Unstake the full amount 2) Upgrade your node @@ -123,7 +125,7 @@ service rusk start ``` #### How can I run a Dusk node on Docker? -We don't support a production-ready Docker image for Rusk. To run Rusk through Docker as ephemeral (non-persistent storage), you can use the following command: +We don't support a production-ready Docker image for Rusk. To run Rusk through Docker as ephemeral (non-persistent storage), you can use the following command: ```bash docker run -p 9000:9000/udp -p 8080:8080/tcp dusknetwork/node @@ -138,7 +140,7 @@ Bootstrapper nodes are used during initial synchronization to help your node joi If you configure your node to use a different port (e.g., 42069), it’s crucial to ensure that other nodes, including bootstrappers, are aware of and can adapt to this port. Otherwise, they will not route messages to your node. **With the Node Installer:** -If you are using the Node Installer, it is recommended to specify Kadcast configuration updates in `/opt/dusk/services/rusk.conf.user`. This file takes precedence over `rusk.conf.default` and ensures your changes are retained during updates. +If you are using the Node Installer, it is recommended to specify Kadcast configuration updates in `/opt/dusk/services/rusk.conf.user`. This file takes precedence over `rusk.conf.default` and ensures your changes are retained during updates. You can add or modify the following section: diff --git a/src/content/docs/operator/archive-node.md b/src/content/docs/operator/archive-node.md index c9129e47..0886bd4e 100644 --- a/src/content/docs/operator/archive-node.md +++ b/src/content/docs/operator/archive-node.md @@ -1,5 +1,5 @@ --- -title: Archive nodes +title: Run an archive node description: Learn about Dusk archive nodes that store and give access to Dusk’s historical data. --- @@ -12,7 +12,7 @@ In short, archive nodes: - Can participate in consensus, by staking DUSK. However, they are not required to. :::tip[Run an Archive node] -If you want to quickly launch & run an archive node, you can use the node installer by following [the archive guide](/operator/guides/archive-node). +If you want to quickly launch & run an archive node, you can use the node installer by following [the archive guide](/operator/archive-node). ::: ## Archive Node Specifications @@ -22,3 +22,81 @@ Archive nodes store and serve historical data and require large storage capacity | CPU | RAM | Storage | Network Connection | | :------------- | :--- | :------ | :----------------- | | 4 cores; 2 GHz | 8 GB | 500 GB | 100 Mbps | + +## Run an archive node +> A step-by-step guide to setting up a Dusk archive node. + +The following guide will explain you how to install and setup an archive node on Ubuntu 24.04 through the [node installer](https://github.com/dusk-network/node-installer). This installer will set up Rusk as a service on your server, preconfigure parts of the node, and provide a couple of helper scripts. + +Install Rusk with the archive feature enabled by pasting the following command in your server terminal: +```sh +curl --proto '=https' --tlsv1.2 -sSfL https://github.com/dusk-network/node-installer/releases/latest/download/node-installer.sh | sudo bash -s -- --feature archive +``` + +This will install an archive node with the network being set to mainnet. + +## Configure Rusk + +You now should have successfully installed Rusk. + +A quick check with: + +```sh +ruskquery version +``` + +Should tell you, that you are running the latest installer version. + +## Start your node + +If you've configured everything correctly, you can now start rusk: +```sh +service rusk start +``` + +Your node will now start syncing. You can check if it indeed is by running: +```sh +ruskquery block-height +``` + +It is best to wait until your node is synced up. You can find the latest block height on [the block explorer](https://explorer.dusk.network/). Alternatively, consider [fast-syncing](/operator/guides/fast-sync) for a quicker method. + +## Enable http + +If you want to serve archive data to the outside world, your node needs to enable the http capabilities. This can be done by adding + +```toml +// rusk.toml +[http] +listen = true +listen_address = '0.0.0.0:8080' +``` + +To your rusk.toml file in your system's `/opt/dusk/conf` folder. That's it. + +Now you can query the archive for data with an external client application. + +## Test archive endpoint + +You can check which graphQL endpoints are available by calling the endpoint with an empty query: +```bash +curl -i -H 'Content-Type: application/json' \ + -X POST -d "" https://yournodeIPorDomain.example +``` + +This should now return a different list than a normal node returns. An example endpoint that is now available is the **checkBlock** endpoint, which returns true or false whether a block height matches a specific block hash, which can also be queried only for finalized blocks. + +In order to test this endpoint, you can run the following command. + +```bash +curl -i -H 'Content-Type: application/json' \ + -X POST -d "query { checkBlock(height: 1, hash: \"abc\", onlyFinalized: true) }" https://yournodeIPorDomain.example +``` + +which should return `{"checkBlock":false}` + +## Stake with archive node + +It is possible to stake and participate in consensus while the archive node is running. This is usually not recommended, but is possible since the archive is built on top of a normal provisioner node and therefore has all the capabilities to do so. + +You can read the [node wallet guide](/operator/guides/node-wallet-setup) for a step-by-step instruction on setting up the wallet, depending on if you want the archive node to participate in consensus too or not. diff --git a/src/content/docs/operator/from-source.md b/src/content/docs/operator/from-source.md deleted file mode 100644 index d8e07f41..00000000 --- a/src/content/docs/operator/from-source.md +++ /dev/null @@ -1,218 +0,0 @@ ---- -title: Install Rusk from source -description: Learn how to install and configure a Dusk node. ---- - -:::note[Node Installer] -This page here is for advanced users looking for additional information or custom setups. - -It is advised to use the Node installer to [quickly launch your node on Dusk](/operator/guides/provisioner-node). - -The node installer setups rusk.toml file for you but for advance users this tutorial will tell you how to setup that file -::: - -Rusk contains the software needed to run a Dusk node. Users can set specific compilation flags to configure their node for different roles, allowing it to perform tasks like participating in consensus, validating transactions, and storing historical data. - -Rusk supports different feature setups: -- Provisioner: to stake and participates in consensus. -- Archive node: to store and serve historical data. -- Prover: to compute Zero-Knowledge Proofs. - -The node software has been tested on x86-64/AMD64 and ARM architectures. The above node types have different hardware requirements, which can be found on their respective pages. - -To install Rusk, you can either: -- Use the node installer (recommended) -- Build from source -- Use docker (not recommended for production environment) - -## Requirements - -This page is tailored for Linux servers, if you are using another operating system you may encounter compatibility issues. - -## Build from source - -The majority of Dusk software is written in Rust. To compile our code, we will first need to make sure it's installed. Refer to Rustup on how to install Rust. - -**Other Software Requirements**: To follow the next steps, you need to have the following software installed:: `curl`, `zip`, `libssl-dev`, `rustc`, `clang`, `gcc` and `git`. These will be installed by the dev-setup script which is shown below - -First to compile and run the Dusk node from source, run the following commands - -Clone the Rusk repository. Make sure you modify the command to suit the branch you want to get. The command below will not necessarily fetch a branch compatible with the latest network release and specifications. - -Make sure you follow these commands in sequence. - -```bash -git clone https://github.com/dusk-network/rusk.git -cd rusk -``` - -Run the setup script in the scripts folder of rusk, which can take care of dependencies. - -```bash -bash scripts/dev-setup.sh -``` - -Generate the keys used by the circuits: - -```bash -make keys -``` - -Compile all the genesis contracts: - -```bash -make wasm -``` - -:::note[Generating genesis contracts] -The duskc compiler, required for compiling contracts, might not be available for your target system. If you encounter an error while running make wasm, you can work around this limitation by running `make wasm` on a supported system. Once the process completes, copy the `target/release/dusk` folder from the supported system into the target folder on your unsupported machine. This serves as a temporary solution to bypass the duskc compiler requirement. -::: - -Then we compile the rusk binary, depending on the type of node you want, you will have to run a different command: - -As provisioner - -```bash -cargo b --release -p dusk-rusk -``` - -Or as archival - -```bash -cargo b --release --features archive -p dusk-rusk -``` - -Or as prover only - -```bash -cargo b --release --no-default-features --features prover -p dusk-rusk -``` - -After you compile your binary follow the setup below to complete the setup of your node - -### Setting up your node - -After compiling we need to setup some configuration file and state for the particular network you are running the node for, for this example we'll configure the node to run on dusk mainnet. - -Now before building the node we need the following: - -1. The location of the rusk.toml configuration file -2. The location of the database path -3. `DUSK_CONSENSUS_KEYS_PASS` which is the password for your consensus keys -4. Base state of the mainnet -5. `RUSK_STATE_PATH` path of our state - -Let start by creating a `~/.dusk/rusk` at your home directory. This is where we'll setup our node: - -``` -mkdir /Users/username/.dusk/rusk -cd /Users/username/.dusk/rusk -``` - -:::note[Default `RUSK_PROFILE_PATH`] -The default location if the `RUSK_PROFILE_PATH` is not set is `$HOME/.dusk/rusk` but for this tutorial we explicitly create it anyways -::: - -We're now in our profile folder. Then we'll copy the rusk binary we compiled into this folder - -``` -cp rusk/target/release/rusk /Users/username/.dusk/rusk/ -``` - -We'll create a `genesis.toml` file to specify our base state URL -this URL below is for **mainnet** - -``` -cat > ~/.dusk/rusk/genesis.toml < -listen_address = - -... -``` - - -To determine your public and listen address you can run this script used by the node installer https://github.com/dusk-network/node-installer/blob/main/bin/detect_ips.sh - -Now we just need `DUSK_CONSENSUS_KEYS_PASS` set: - -``` -export DUSK_CONSENSUS_KEYS_PASS="password" -``` - -After this we should be good, we run our node using the following command, make sure to specify your state URL - -``` -RUSK_STATE_PATH=/Users/username/.dusk/mainnet_state ./rusk --config ./rusk.toml -``` - -You should see the following in the terminal - -``` -2025-01-15T17:19:59.791200Z WARN node: wait_for_alive_nodes -2025-01-15T17:20:00.792778Z WARN node: wait_for_alive_nodes -2025-01-15T17:20:00.792777Z WARN node: wait_for_alive_nodes -2025-01-15T17:20:00.792815Z WARN node::network: event="Not enought alive peers to send msg, increased" topic=GetMempool requested=5 current=0 increased=0 -2025-01-15T17:20:00.792815Z WARN node::network: event="Not enought alive peers to send msg, increased" topic=GetBlocks requested=16 current=0 increased=0 -... -``` - -This means you probably haven't port forwarded yet, checkout below on how to do that - -:::note[No such base commit error] -When you get the following `VM Error: No such base commit error` try regenerating your state, if it still persists, make sure the path in the `rusk.toml` file is correct, follow all the steps above correctly to mitigate this error -::: - -#### Networking - -As Dusk uses an ultra-efficient P2P UDP network protocol called Kadcast, the network requirements are minimal but should maintain symmetrical, stable, low-latency connections. - -For external network connectivity, ensure that your firewall and router's ports are forwarded correctly: - -- **9000/udp**: Required for Kadcast consensus messages. -- **8080/tcp**: Optional HTTPS API for querying the node. - -:::note[Note] -The ports are configurable either as option to the node binary or by setting them in the configuration files. The node installer automatically configures the necessary ports. -::: - -## Troubleshooting Tips - -* **Installation Issues**: Ensure your operating system is up-to-date, you have adequate permissions and all the necessary prerequisite software is installed. -* **Network Errors**: Check your internet connection and verify UDP ports are open if connecting to an external network. diff --git a/src/content/docs/operator/guides/archive-node.md b/src/content/docs/operator/guides/archive-node.md deleted file mode 100644 index 20eba46f..00000000 --- a/src/content/docs/operator/guides/archive-node.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Run an archive node -description: A step-by-step guide to setting up a Dusk archive node. ---- - -This guide will explain you how to install and setup an archive node on Ubuntu 24.04 through the [node installer](https://github.com/dusk-network/node-installer). This installer will set up Rusk as a service on your server, preconfigure parts of the node, and provide a couple of helper scripts. - -Install Rusk with the archive feature enabled by pasting the following command in your server terminal: -```sh -curl --proto '=https' --tlsv1.2 -sSfL https://github.com/dusk-network/node-installer/releases/latest/download/node-installer.sh | sudo bash -s -- --feature archive -``` - -This will install an archive node with the network being set to mainnet. - -## Configure Rusk - -You now should have successfully installed Rusk. - -A quick check with: - -```sh -ruskquery version -``` - -Should tell you, that you are running the latest installer version. - -## Start your node - -If you've configured everything correctly, you can now start rusk: -```sh -service rusk start -``` - -Your node will now start syncing. You can check if it indeed is by running: -```sh -ruskquery block-height -``` - -It is best to wait until your node is synced up. You can find the latest block height on [the block explorer](https://explorer.dusk.network/). Alternatively, consider [fast-syncing](/operator/guides/fast-sync) for a quicker method. - -## Enable http - -If you want to serve archive data to the outside world, your node needs to enable the http capabilities. This can be done by adding - -```toml -// rusk.toml -[http] -listen = true -listen_address = '0.0.0.0:8080' -``` - -To your rusk.toml file in your system's `/opt/dusk/conf` folder. That's it. - -Now you can query the archive for data with an external client application. - -## Test archive endpoint - -You can check which graphQL endpoints are available by calling the endpoint with an empty query: -```bash -curl -i -H 'Content-Type: application/json' \ - -X POST -d "" https://yournodeIPorDomain.example -``` - -This should now return a different list than a normal node returns. An example endpoint that is now available is the **checkBlock** endpoint, which returns true or false whether a block height matches a specific block hash, which can also be queried only for finalized blocks. - -In order to test this endpoint, you can run the following command. - -```bash -curl -i -H 'Content-Type: application/json' \ - -X POST -d "query { checkBlock(height: 1, hash: \"abc\", onlyFinalized: true) }" https://yournodeIPorDomain.example -``` - -which should return `{"checkBlock":false}` - -## Stake with archive node - -It is possible to stake and participate in consensus while the archive node is running. This is usually not recommended, but is possible since the archive is built on top of a normal provisioner node and therefore has all the capabilities to do so. - -You can read the [node wallet guide](/operator/guides/node-wallet-setup) for a step-by-step instruction on setting up the wallet, depending on if you want the archive node to participate in consensus too or not. diff --git a/src/content/docs/operator/guides/nocturne-faucet.md b/src/content/docs/operator/guides/nocturne-faucet.md deleted file mode 100644 index cf5eba19..00000000 --- a/src/content/docs/operator/guides/nocturne-faucet.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Nocturne Faucet Guide -description: This guide will explain how to obtain nDUSK for the running Nocturne testnet. ---- - -This guide will explain how to obtain nDUSK for the running Nocturne testnet. - -## How to get testnet tokens - -The Dusk Nocturne testnet uses a Discord bot to distribute Nocturne tokens (nDUSK). - -In order to access it, follow these steps: - -1. Access the [Dusk Discord server](https://discord.gg/dusk-official). -2. Among the team members, locate the bot "Dusk Testnet Faucet." -3. Right-click and select "Message". -4. Send `!dusk` as a command. The bot will reply, asking for your Testnet wallet address. -5. Done! Your transaction will be queued, and you will see it in your wallet once processed. - -There is currently a limit of 1 transaction per user/wallet every 24 hours. - -## FAQ - -**Q: How many times can I use the faucet?** - -There is currently a 24-hour cooldown period before you can ask for nDUSK again with the same Discord username or wallet address. - -**Q: How do I access the Dusk Discord server?** - -You can access the Discord server by clicking on [this link](https://discord.gg/dusk-official). - -**Q: How long before I will see my nDUSK?** - -Once the transaction is submitted, it will be processed in a queue. -The time required to see the nDUSK in your account may vary according to network congestion and the number of people currently requesting nDUSK, but it usually takes just a few minutes. -If the network is experiencing a large number of faucet requests, the transaction might take longer than usual to be processed. - -**Q: What if I want to run multiple nodes?** - -If you need nDUSK for multiple accounts, you can either wait 24 hours and then send again to the other wallet, or send your nDUSK to the first wallet, and then transfer some of it to the second wallet yourself. - -**Q: I got error X, what should I do?** - -If you encounter an error with the Discord faucet, please get in touch in our Telegram or Discord channel. diff --git a/src/content/docs/operator/guides/node-wallet-setup.md b/src/content/docs/operator/guides/node-wallet-setup.md index 93baa80e..4a2a1d39 100644 --- a/src/content/docs/operator/guides/node-wallet-setup.md +++ b/src/content/docs/operator/guides/node-wallet-setup.md @@ -6,7 +6,7 @@ description: Learn how to setup your Dusk wallet for staking and node running. :::note[Node Installer] This guide assumes that you have already installed Rusk using the node-installer. -You can use the node installer guide to [quickly launch your Provisioner node](/operator/guides/provisioner-node). +You can use the node installer guide to [quickly launch your Provisioner node](/operator/provisioner). ::: This guide explains setting up the wallet and the last steps needed to start running your node. @@ -77,7 +77,7 @@ Compare your node's block height to the [block explorer](https://explorer.dusk.n ## Testnet Faucet -You can request 5000 nDUSK from our [Discord faucet](/operator/guides/nocturne-faucet). The minimum stake is 1000 nDUSK. +You can request 5000 nDUSK from our [Discord faucet](/operator/networks#how-to-get-testnet-tokens). The minimum stake is 1000 nDUSK. ## Stake your DUSK @@ -90,7 +90,7 @@ A Dusk stake involves two roles: - **Consensus Key**: Used by your node to participate in consensus to vote and sign blocks. - **Owner Key**: The key/address that can `unstake` and `withdraw` your stake. -If you do not specify an owner when staking, the consensus key automatically becomes the owner. This is the simplest setup, but it has different security implications than using a separate owner key. +If you do not specify an owner when staking, the consensus key automatically becomes the owner. This is the simplest setup, but it has different security implications than using a separate owner key. ### Option 1: Keep Owner and Consensus the same (default) @@ -102,7 +102,7 @@ rusk-wallet stake --amt 1000 # Replace with your desired amount Simpler setup, only one address to manage. **Cons**: -If the node is compromised and the attacker gains access to the consensus key or an unprotected wallet, they can steal your funds. +If the node is compromised and the attacker gains access to the consensus key or an unprotected wallet, they can steal your funds. This option is acceptable if your server is well-hardened (SSH key-only access, no password logins, firewall, restricted users). @@ -115,9 +115,9 @@ rusk-wallet stake --amt 1000 --owner # Replace with an address f Replace with another address (e.g., from Profile 2) derived from the same mnemonic you used to set up the node wallet. **Pros**: -Even if your node or consensus key is compromised, only the owner key can unstake or withdraw funds. +Even if your node or consensus key is compromised, only the owner key can unstake or withdraw funds. -**Cons**: +**Cons**: Slightly more operational overhead. You must keep the owner key safe and available whenever you need to unstake or restake. **Security note**: This is most effective if you do not store the mnemonic on the server, or if you use a strong wallet password different from the provisioner key password. diff --git a/src/content/docs/operator/guides/upgrade-node.mdx b/src/content/docs/operator/guides/upgrade-node.mdx index 97737b52..9576c28c 100644 --- a/src/content/docs/operator/guides/upgrade-node.mdx +++ b/src/content/docs/operator/guides/upgrade-node.mdx @@ -95,7 +95,7 @@ rusk-wallet stake-info ``` If you already have DUSK staked, wait until the chain starts producing blocks. You can check [our explorer](https://testnet.apps.dusk.network/explorer/) to see if the chain is progressing or when it will produce the genesis block. -1. If you do not have testnet DUSK, request nDUSK from the [faucet](/operator/guides/nocturne-faucet). +1. If you do not have testnet DUSK, request nDUSK from the [faucet](/operator/networks#how-to-get-testnet-tokens). 2. Stake your nDUSK: ```sh diff --git a/src/content/docs/operator/installation.md b/src/content/docs/operator/installation.md deleted file mode 100644 index 53ca7ffd..00000000 --- a/src/content/docs/operator/installation.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: Install Rusk Manually -description: Learn how to install and configure a Dusk node. ---- - -:::note[Node Installer] -This page here is for advanced users looking for additional information or custom setups. - -It is advised to use the Node installer to [quickly launch your node on Dusk](/operator/guides/provisioner-node). -::: - -Rusk contains the software needed to run a Dusk node. Users can set specific compilation flags to configure their node for different roles, allowing it to perform tasks like participating in consensus, validating transactions, and storing historical data. - -Rusk supports different feature setups: -- [Provisioner](/operator/provisioner) : to stake and participates in consensus. -- [Archive node](/operator/archive-node) : to store and serve historical data. -- [Prover](/operator/prover) : to compute Zero-Knowledge Proofs. - -The node software has been tested on x86-64/AMD64 and ARM architectures. The above node types have different hardware requirements, which can be found on their respective pages. - -To install Rusk, you can either: -- Use the node installer (recommended) -- Build from source -- Use docker (not recommended for production environment) - -## Requirements - -This page is tailored for Linux servers, if you are using another operating system you may encounter compatibility issues. - -## Node Installer - -If you want to spin up a Provisioner node on the Nocturne testnet, you can use the node installer script. This installer will set up Rusk as a service, preconfigure parts of the node, and provide a couple of helper scripts. - -You can install Rusk with the **default mainnet configuration** by pasting the following command in your terminal: -```sh -curl --proto '=https' --tlsv1.2 -sSfL https://github.com/dusk-network/node-installer/releases/latest/download/node-installer.sh | sudo bash -``` -:::note[Node Installer] -For more information on the Node Installer, such as networks and features you can set up — -checkout the node-installer README -::: - -:::note[UFW and other configurations] -The script may enable ufw and apply other configurations to your system. If you want to avoid this, you can disable ufw or build from source. -::: - -## Build from source - -Rusk can be built from source by following this [guide](/operator/from-source). - -#### Networking - -As Dusk uses an ultra-efficient P2P UDP network protocol called Kadcast, the network requirements are minimal but should maintain symmetrical, stable, low-latency connections. - -For external network connectivity, ensure that your firewall and router's ports are forwarded correctly: - -- **9000/udp**: Required for Kadcast consensus messages. -- **8080/tcp**: Optional HTTPS API for querying the node. - -:::note[Note] -The ports are configurable either as option to the node binary or by setting them in the configuration files. The node installer automatically configures the necessary ports. -::: - -## Docker Installation - -This guide will take you through the process using Docker, for running a local Dusk node. - -Docker packages applications into containers that include all dependencies, ensuring a consistent runtime environment. This ensures that software always runs consistently, regardless of where it is installed. - -:::note[Notice] -The following guide is intended to help you set up a local node for testing and development purposes only. It is not recommended for production use, as there is no guide or explanation for running a production node within Docker. Docker is used here to facilitate convenient local testing and to provide developers with a dedicated node for API testing. -::: - - -### Prerequisites - -1. 🐳 **Docker**: If you don't have Docker installed, please follow the [official guide](https://docs.docker.com/desktop/) -2. 🛜 **Internet Connection**: Required to download the Docker image and necessary files. -3. 🛠️ **Git**: Optional, but recommended. Useful for retrieving the node code. Git can be downloaded here -4. 💻 **Terminal**: To execute the steps in the Step-By-Step below, you will need to use a terminal application. -5. 🎛️ **x86-AMD64**: To create the Docker Image, a processor with the x86-AMD64 architecture is required. - -:::tip[Using DockerHub] -If you want to quickstart using a prebuilt docker image, run the following command: -```sh -docker run -p 9000:9000/udp -p 8080:8080/tcp dusknetwork/node -``` -::: - -### Step-by-Step Instructions - -#### 1. Get the Dusk node files - -There are two ways to get the software, cloning the repository using git, or [simply downloading from github](https://github.com/dusk-network/rusk) - -```sh -git clone https://github.com/dusk-network/rusk.git -``` - -#### 2. Build Docker Image - -With Docker installed and the repository files obtained, let's build the Docker image. Note that this can take 15 to 20 minutes. - -The most up to date commands can be found in the [readme of the repository](https://github.com/dusk-network/rusk?tab=readme-ov-file#-docker-support) - -## Troubleshooting Tips - -* **Installation Issues**: Ensure your operating system is up-to-date, you have adequate permissions and all the necessary prerequisite software is installed. -* **Network Errors**: Check your internet connection and verify UDP ports are open if connecting to an external network. diff --git a/src/content/docs/operator/networks.md b/src/content/docs/operator/networks.md index 0e33fe06..aa0c24a6 100644 --- a/src/content/docs/operator/networks.md +++ b/src/content/docs/operator/networks.md @@ -3,7 +3,7 @@ title: Choose a Network description: Explore the scope of different Dusk’s environments, including testnet and mainnet. --- -Dusk offers multiple network environments to support different stages of development, testing, and live usage. Each network serves a unique purpose, allowing developers, testers, and users to interact with the Dusk network under various conditions. +Dusk offers multiple network environments to support different stages of development, testing, and live usage. Each network serves a unique purpose, allowing developers, testers, and users to interact with the Dusk network under various conditions. # Network Overview @@ -18,7 +18,7 @@ The available networks include: --- -You can find instructons on how to run a node in the [Provisioner Node Guide](/operator/guides/provisioner-node). +You can find instructons on how to run a node in the [Provisioner Node Guide](/operator/provisioner). ## Mainnet @@ -43,6 +43,21 @@ Some of the functions for the Nocturne Testnet are: - Supporting community-run nodes for stress-testing and performance assessments. +### How to get testnet tokens + +The Dusk Nocturne testnet uses a Discord bot to distribute Nocturne tokens (nDUSK). + +In order to access it, follow these steps: + +1. Access the [Dusk Discord server](https://discord.gg/dusk-official). +2. Among the team members, locate the bot "Dusk Testnet Faucet." +3. Right-click and select "Message". +4. Send `!dusk` as a command. The bot will reply, asking for your Testnet wallet address. +5. Done! Your transaction will be queued, and you will see it in your wallet once processed. + +There is currently a limit of 1 transaction per user/wallet every 24 hours. + + ## Lunare Devnet The Lunare Devnet is an experimental sandbox environment for internal development and initial testing of Dusk’s newest features. Lunare enables Dusk’s engineering team to iterate quickly on early-stage functionalities, benchmark them, and troubleshoot issues in a controlled setting. While Lunare offers a flexible testing ground, it is reserved for internal use and is not open to the general public. diff --git a/src/content/docs/operator/overview.mdx b/src/content/docs/operator/overview.mdx index 3265a4ef..076ade2c 100644 --- a/src/content/docs/operator/overview.mdx +++ b/src/content/docs/operator/overview.mdx @@ -4,15 +4,15 @@ description: A complete guide to setting up, configuring, and operating a node o --- import { LinkCard, Card, CardGrid } from '@astrojs/starlight/components'; -Welcome to the Dusk Node documentation section. This documentation is for anyone interested in running a Dusk node. Here you can find information about the different types of nodes, the requirements for running a node, and the different ways to set up a node. +This Dusk Node documentation documentation is for anyone interested in running a Dusk node. Here you can find information about the different types of nodes, the requirements for running a node, and the different ways to set up a node. ## Setting Up & Running a Node There are multiple ways to set up a Dusk node. The pages below provide guides on how to run a node. - - + + diff --git a/src/content/docs/operator/prover.md b/src/content/docs/operator/prover.md index a9c257e4..b303a2ef 100644 --- a/src/content/docs/operator/prover.md +++ b/src/content/docs/operator/prover.md @@ -1,5 +1,5 @@ --- -title: Provers +title: Run a Prover node description: Learn about Dusk Provers for generating zero-knowledge proofs within Dusk. --- diff --git a/src/content/docs/operator/provisioner.md b/src/content/docs/operator/provisioner.md deleted file mode 100644 index 7456dbf3..00000000 --- a/src/content/docs/operator/provisioner.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Provisioner nodes -description: Discover what a Dusk Full Validator Node (Provisioner) is and how to participate in consensus and start staking. ---- - -Dusk supports multiple node configurations, with Provisioners being the full node equipped with participating in consensus. Participating in consensus is incentivized by the protocol through staking rewards. As the backbone of network security and transaction validation, Provisioners play a crucial role in processing and appending new blocks to the Dusk blockchain. - -Provisioners are required to stake a **minimum of 1000 DUSK** to participate in the consensus mechanism. In return, they earn rewards for validating transactions and generating blocks, providing a financial incentive for securing the network. These rewards not only compensate users for locking up their assets but also encourage ongoing participation in block creation and voting. - -:::tip[Run a Provisioner] -If you want to quickly launch & run a Provisioner, you can use the node installer by following [the provisioner node guide](/operator/guides/provisioner-node). -::: - -## Provisioner Specifications - -The following specifications support Provisioner nodes with limited proving capacity. It is always recommended to have at least 2 cores available. - -| CPU | RAM | Storage | Network Connection | -| :------------- | :--- | :------ | :----------------- | -| 2 cores; 2 GHz | 4 GB | 50 GB | 10 Mbps | diff --git a/src/content/docs/operator/guides/provisioner-node.mdx b/src/content/docs/operator/provisioner.mdx similarity index 71% rename from src/content/docs/operator/guides/provisioner-node.mdx rename to src/content/docs/operator/provisioner.mdx index 00240bcd..8966e29a 100644 --- a/src/content/docs/operator/guides/provisioner-node.mdx +++ b/src/content/docs/operator/provisioner.mdx @@ -1,9 +1,24 @@ --- -title: Run a Provisioner on Dusk -description: A step-by-step guide on installing the Dusk node. +title: Run a provisioner node +description: Discover what a Dusk Full Validator Node (Provisioner) is and how to run such a node --- -In this guide, we’ll be using [DigitalOcean](https://www.digitalocean.com/) (DO) as our go-to [Virtual Private Server](https://en.wikipedia.org/wiki/Virtual_private_server) (VPS) service. The same can be replicated on Vultr, AWS, Hetzner, or any other cloud service or for node runners at home. While it is indeed possible to run a node on home infrastructure, this guide will not deal with those types of setups. +Provisioner nodes are full nodes equipped with participating in consensus. Participating in consensus is incentivized by the protocol through staking rewards. As the backbone of network security and transaction validation, Provisioners play a crucial role in processing and appending new blocks to the Dusk blockchain. + +Provisioners are required to stake a **minimum of 1000 DUSK** to participate in the consensus mechanism. In return, they earn rewards for validating transactions and generating blocks, providing a financial incentive for securing the network. These rewards not only compensate users for locking up their assets but also encourage ongoing participation in block creation and voting. + +## Provisioner Specifications + +The following specifications support Provisioner nodes with limited proving capacity. It is always recommended to have at least 2 cores available. + +| CPU | RAM | Storage | Network Connection | +| :------------- | :--- | :------ | :----------------- | +| 2 cores; 2 GHz | 4 GB | 50 GB | 10 Mbps | + +## Run a Provisioner on Dusk +> A step-by-step guide on installing the Dusk node. + +In the following guide, we’ll be using [DigitalOcean](https://www.digitalocean.com/) (DO) as our go-to [Virtual Private Server](https://en.wikipedia.org/wiki/Virtual_private_server) (VPS) service. The same can be replicated on Vultr, AWS, Hetzner, or any other cloud service or for node runners at home. While it is indeed possible to run a node on home infrastructure, this guide will not deal with those types of setups. We work under the assumption that you’ve already created an account for your respective service, and provided it with a payment method. If not, you can get a $200 credit by using [our referral link](https://m.do.co/c/9ae612e34de9). @@ -11,29 +26,29 @@ We work under the assumption that you’ve already created an account for your r DO uses droplets, which are Linux-based virtual machines. When you’re [logged in](https://cloud.digitalocean.com/login) and have set up a default project, navigate to _Droplets_ under the _Manage_ section of your project, and click on [_Create Droplet_](https://cloud.digitalocean.com/droplets/new). -![Create droplet page.](../../../../assets/node-guide/create-droplet.png) +![Create droplet page.](../../../assets/node-guide/create-droplet.png) On the _Create Droplets_ page, select any of the provided regions under the _Choose Region_ header. Choosing different regions is good for decentralization and resilience. Under _Choose an image_, pick Ubuntu version 24.04 (LTS) x64. -![Select region and image for the droplet.](../../../../assets/node-guide/region-image-droplet.png) +![Select region and image for the droplet.](../../../assets/node-guide/region-image-droplet.png) Next, we have to pick the size of the droplet. The [node requirements](/operator/provisioner#provisioner-specifications) for a provisioner node are in line with the _SHARED CPU_ -> _Regular_ -> $24/mo option. Select it. -![Select size of the droplet.](../../../../assets/node-guide/requirements-droplet.png) +![Select size of the droplet.](../../../assets/node-guide/requirements-droplet.png) Choose an authentication method to access your droplet. Using a SSH key is more secure, but you can also use a password if you prefer. We recommend the SSH key approach. You can follow DOs instructions here: [How to Add SSH Keys to New or Existing Droplets](https://docs.digitalocean.com/products/droplets/how-to/add-ssh-keys/) -![Set an authentication method.](../../../../assets/node-guide/authenticate-droplet.png) +![Set an authentication method.](../../../assets/node-guide/authenticate-droplet.png) That's it for creating your droplet! Give it a hostname, and click on _Create Droplet_: -![Create the droplet.](../../../../assets/node-guide/finish-droplet.png) +![Create the droplet.](../../../assets/node-guide/finish-droplet.png) DO will now set the droplet up for you. This can take a minute: -![Droplet being created.](../../../../assets/node-guide/droplet-creation.png) +![Droplet being created.](../../../assets/node-guide/droplet-creation.png) ## Configure Firewall @@ -46,7 +61,7 @@ The Rusk node uses the Kadcast protocol to communicate messages between nodes on If you're using DO or a similar cloud provider, configure a firewall group. Navigate to _Networking_ -> _Firewalls_ under the _Manage_ section of your project. Click on the [_Create Firewall_](https://cloud.digitalocean.com/networking/firewalls) button. -![Create firewall page.](../../../../assets/node-guide/create-firewall.png) +![Create firewall page.](../../../assets/node-guide/create-firewall.png) Give the firewall a name, open UDP under port 9000 (optionally TCP under 8080 too). Leave all the Outbound rules as they are. @@ -54,7 +69,7 @@ Apply the rules to the node droplet you made. Your firewall should look as follows: -![Configure firewall.](../../../../assets/node-guide/configure-firewall.png) +![Configure firewall.](../../../assets/node-guide/configure-firewall.png) Click on _Create Firewall_ to apply this firewall to your node's droplet. @@ -78,15 +93,15 @@ For non-default SSH ports, replace `ssh` with the specific port number. Adjust c Navigate back to your [droplets overview](https://cloud.digitalocean.com/droplets) and select your droplet: -![Droplet overview.](../../../../assets/node-guide/droplet-overview.png) +![Droplet overview.](../../../assets/node-guide/droplet-overview.png) You can connect to your node through SSH on your local machine, or simply click on _Console_ on your droplets page: -![Connect to droplet through web UI.](../../../../assets/node-guide/droplet-console.png) +![Connect to droplet through web UI.](../../../assets/node-guide/droplet-console.png) A terminal should pop-up and connect you to your Droplet -![Droplet terminal.](../../../../assets/node-guide/droplet-terminal.png) +![Droplet terminal.](../../../assets/node-guide/droplet-terminal.png) ### (Optional) User and Group Permissions @@ -173,3 +188,4 @@ You should see the latest version number confirming a successful installation. Now that you have setup rusk, it's time to setup your wallet to finally start participating in consensus You can read the [node wallet guide](/operator/guides/node-wallet-setup) for a step-by-step instruction how to set it up on the server. + diff --git a/src/sidebars/operatorSidebar.js b/src/sidebars/operatorSidebar.js index 0c6c0a20..4a62b1ba 100644 --- a/src/sidebars/operatorSidebar.js +++ b/src/sidebars/operatorSidebar.js @@ -5,26 +5,18 @@ export default function sidebar(currentPath) { createLink("Overview", "/operator/overview"), createGroup("Run a node", currentPath, [ - { label: "Provisioner node", href: "/operator/provisioner" }, - { label: "Archive Node", href: "/operator/archive-node" }, - { label: "Provers", href: "/operator/prover" }, + { label: "Run a provisioner node", href: "/operator/provisioner" }, + { label: "Run an archive node", href: "/operator/archive-node" }, + { label: "Run a prover node", href: "/operator/prover" }, + { label: "Setup wallet on Node", href: "/operator/guides/node-wallet-setup" }, + { label: "Fast-Sync a Node", href: "/operator/guides/fast-sync" }, + { label: "Manually Re-Sync a Node", href: "/operator/guides/manual-resync" }, + { label: "Upgrade a Node", href: "/operator/guides/upgrade-node" }, { label: "Choose a Network", href: "/operator/networks" }, { label: "Maintenance & Monitoring", href: "/operator/maintenance-monitoring" }, - { label: "Manually Install Rusk", href: "/operator/installation/" }, - { label: "Install Rusk from source", href: "/operator/from-source/" }, { label: "FAQ", href: "/operator/faq" }, { label: "Troubleshooting", href: "/operator/troubleshooting" }, //{ label: "Upgrades history", href: "/operator/introduction/history" }, ], false), - - createGroup("Guides", currentPath, [ - { label: "Run a Provisioner Node", href: "/operator/guides/provisioner-node" }, - { label: "Run an Archive Node", href: "/operator/guides/archive-node" }, - { label: "Setup wallet on Node", href: "/operator/guides/node-wallet-setup" }, - { label: "Fast-Sync a Node", href: "/operator/guides/fast-sync" }, - { label: "Manually Re-Sync a Node", href: "/operator/guides/manual-resync" }, - { label: "Upgrade a Node", href: "/operator/guides/upgrade-node" }, - { label: "Nocturne faucet", href: "/operator/guides/nocturne-faucet" }, - ], false), ]; }