diff --git a/.gitignore b/.gitignore index edf80f5..0be35d6 100644 --- a/.gitignore +++ b/.gitignore @@ -19,3 +19,6 @@ pnpm-debug.log* # macOS-specific files .DS_Store + +# Local analytics exports (do not commit) +Pages_and_screens_*.csv diff --git a/src/content/docs/developer/overview.mdx b/src/content/docs/developer/overview.mdx index e84196f..b416de2 100644 --- a/src/content/docs/developer/overview.mdx +++ b/src/content/docs/developer/overview.mdx @@ -77,6 +77,6 @@ If that’s you, start with: You can explore existing contracts and examples in the Dusk repos: -- Protocol contracts in [`rusk/contracts`](https://github.com/dusk-network/rusk/tree/master/contracts) +- Protocol genesis contracts in [`contracts/genesis`](https://github.com/dusk-network/contracts/tree/main/genesis) - The DuskDS example [`my-first-contract`](https://github.com/dusk-network/my-first-contract) - DuskEVM examples in the [DuskEVM docs](/developer/smart-contracts-dusk-evm/deploy-on-evm) diff --git a/src/content/docs/developer/smart-contract/hyperstaking_tech.md b/src/content/docs/developer/smart-contract/hyperstaking_tech.md index 8b6d7b4..8bca3db 100644 --- a/src/content/docs/developer/smart-contract/hyperstaking_tech.md +++ b/src/content/docs/developer/smart-contract/hyperstaking_tech.md @@ -28,7 +28,7 @@ The stake is considered active after a maturity period of 4320 blocks (~12 hours ::: ### Interacting with the Stake Contract -Stake Abstraction requires contracts to interact with the Stake Contract. +Stake Abstraction requires contracts to interact with the Stake Contract. #### Required contract calls @@ -72,7 +72,7 @@ To implement Stake Abstraction, you can refer to Stake Contract defines `stake_from_contract(recv: ReceiveFromContract)`, which requires a `ReceiveFromContract` object. By doing so, it ensures that the calling contract is verified as the stake owner and that the function is only triggered as part of a fund transfer. +This is because the Stake Contract defines `stake_from_contract(recv: ReceiveFromContract)`, which requires a `ReceiveFromContract` object. By doing so, it ensures that the calling contract is verified as the stake owner and that the function is only triggered as part of a fund transfer. In the example implementation, `stake()` does not call `stake_from_contract` directly. Instead, it first transfers the funds and then invokes `stake_from_contract` via a `contract-to-contract` call. @@ -215,4 +215,4 @@ pub fn receive_reward(&mut self, receive: ReceiveFromContract) { let _: () = abi::call(TRANSFER_CONTRACT, "withdraw", &withdraw) .expect("Withdrawing rewards should succeed"); } -``` \ No newline at end of file +``` diff --git a/src/content/docs/learn/core-components.md b/src/content/docs/learn/core-components.md index 74fa1a0..ec2d5a8 100644 --- a/src/content/docs/learn/core-components.md +++ b/src/content/docs/learn/core-components.md @@ -3,23 +3,29 @@ title: Core Components description: Introduction to the core components that power Dusk. --- -Dusk is built with a modular architecture, leveraging tools and components specifically designed to meet [institutional standards](/learn/tokenization-comparison#meeting-institutional-standards) for privacy, regulatory compliance, and secure interactions with regulated assets. These components enable Dusk to support not only the tokenization of real-world assets (RWAs) but also [native issuance](/learn/tokenization-comparison#native-issuance). +Dusk is a modular blockchain architecture built for regulated finance: privacy where it’s needed, transparency where it’s required. -What sets Dusk apart from other blockchains is its tailor-made architecture, driven by continuous cryptographic research to ensure compliance, privacy, and robust network security, providing a reliable foundation to be a **Decentralized Market Infrastructure** (DeMI). +At a high level: + +| Component | Role | Where to go next | +|---|---|---| +| **DuskDS** | Settlement, consensus, and data availability | [Transaction Models](/learn/deep-dive/duskds-tx-models), [Run a node](/operator/overview) | +| **Rusk** | The Rust node implementation that runs DuskDS and exposes APIs | [HTTP API](/developer/integrations/http-api/), GitHub | +| **DuskVM** | WASM execution environment for native smart contracts | [DuskVM deep dive](/learn/deep-dive/dusk-vm/), [Smart Contracts on DuskDS](/developer/smart-contracts-duskds/) | +| **DuskEVM** | OP Stack-based EVM execution environment | [DuskEVM deep dive](/learn/deep-dive/dusk-evm/), [Deploy on DuskEVM](/developer/smart-contracts-dusk-evm/deploy-on-evm/) | +| **Citadel** | Identity and access primitives (selective disclosure) | [Digital Identity protocol](/developer/digital-identity/protocol/) | ## DuskDS -DuskDS is the settlement, consensus, and data availability layer at the foundation of the Dusk architecture. It provides finality, security, and native bridging for all execution environments built on top, including DuskEVM and DuskVM. By modularizing the protocol stack, DuskDS is built to meet institutional demands for compliance, privacy, and performance. +DuskDS is the settlement, consensus, and data availability layer at the foundation of the Dusk architecture. It provides finality, security, and native bridging for execution environments built on top (including DuskEVM and DuskVM). -DuskDS includes Rusk (the node implementation) which is powered by Succinct Attestation (PoS-based consensus), Kadcast (P2P networking layer), and the Transfer and Stake Genesis contracts. Together, these elements form a secure, compliant, and composable environment for regulated financial applications +DuskDS includes Rusk (the node implementation), Succinct Attestation (PoS consensus), Kadcast (P2P networking), and the genesis contracts (stake + transfer). -Through its dual transaction models (Phoenix and Moonlight), it provides a secure settlement and data availability layer for compliant execution environments (such as DuskEVM and DuskVM). For seamless, trustless transfers between execution layers, DuskDS exposes a native bridge. +DuskDS supports two transaction models: **Moonlight** (public) and **Phoenix** (shielded). See: [Transaction Models on Dusk](/learn/deep-dive/duskds-tx-models/). ### Rusk -Rusk can be thought of as the technological heart of the Dusk protocol, similar to the motherboard of a computer. It is the reference implementation of the Dusk protocol in Rust. Rusk serves multiple critical functions. It includes foundational elements like the genesis contracts, such as the transfer and stake contract. It integrates key components such as Plonk, Kadcast and Dusk VM, and supplies host functions to smart contract developers through Dusk Core. Beyond that, Rusk houses the consensus mechanism and node software, maintaining the chain state, database and network. It also provides crucial external APIs through the Rusk Universal Event System (RUES). - -Deep dive into Rusk implementation +Rusk is the Rust implementation of DuskDS. It runs consensus, maintains chain state, and exposes external APIs (including the HTTP API and RUES event system used by wallets, indexers, and integrators). ### Succinct Attestation @@ -27,69 +33,56 @@ Succinct Attestation (SA) is DuskDS’s permissionless, committee-based proof-of At a high level, each round goes through three steps: -1. **Proposal** – a provisioner creates and broadcasts a candidate block. -2. **Validation** – a committee checks the block’s validity. -3. **Ratification** – another committee confirms the validation outcome and finalizes the block. +- **Proposal** – a provisioner creates and broadcasts a candidate block. +- **Validation** – a committee checks the block’s validity. +- **Ratification** – another committee confirms the validation outcome and finalizes the block. For the full protocol specification and security analysis (including committee selection, finality, and slashing), see Section 3 “Consensus mechanism” of the [Dusk Whitepaper (2024)](https://dusk-cms.ams3.digitaloceanspaces.com/Dusk_Whitepaper_2024_4db72f92a1.pdf). ### Transactions in DuskDS -Transactions in DuskDS are managed by the Transfer Contract. The Transfer Contract oversees the handling of both transparent and obfuscated transactions within the network. - -The Transfer Contract supports both a UTXO and account-based model through [Phoenix](/learn/deep-dive/duskds-tx-models) and [Moonlight](/learn/deep-dive/duskds-tx-models) to handle transfers of the native currency, gas payments, and serve as a contract execution entry point. +Transactions in DuskDS are managed by the **Transfer** contract, which supports both public and shielded transfers. -Moonlight provides public transactions, while Phoenix enables shielded transactions. The flexibility of this dual-model allows users to take the best from both privacy and compliance features. +Moonlight is account-based and public. Phoenix is UTXO-based and shielded. Both are used to transfer `DUSK`, pay gas, and act as the entry point for contract execution. ## Execution environments -Dusk is designed to support multiple specialized execution environments, each optimized for distinct use cases (including FHE for confidential transactions to full EVM equivalency). These environments sit atop DuskDS and inherit its secure, compliant settlement guarantees. By separating execution from settlement, Dusk enables high-performance computation without compromising on regulatory alignment or composability. +Dusk supports multiple execution environments on top of DuskDS. Each environment can focus on a specific developer experience (WASM vs EVM) while inheriting settlement and data availability from DuskDS. ### Dusk VM -[Dusk VM](/learn/deep-dive/dusk-vm) is a highly optimized virtual machine built around Wasmtime, a WASM runtime. It is a ZK-friendly virtual machine, enabling the development and execution of privacy-focused smart contracts and applications. - -Dusk VM is fundamentally different from many blockchain VMs in that it not only executes WASM and is able to natively support ZK operations like SNARK verifications, but it also has a completely different way in which it handles memory. - -[Deep dive into Dusk VM](/learn/deep-dive/dusk-vm) +[Dusk VM](/learn/deep-dive/dusk-vm) is a WASM execution environment built around Wasmtime. It’s optimized for Dusk-native smart contracts and privacy-focused applications. ### Dusk EVM -[Dusk EVM](/learn/deep-dive/dusk-evm) is a fully EVM-equivalent execution environment. Built on the OP Stack with support for EIP-4844 (Proto-Danksharding), it enables developers to deploy smart contracts using standard EVM tooling while benefiting from DuskDS's regulatory compliant infrastructure. - -[Deep dive into Dusk EVM](/learn/deep-dive/dusk-evm) +[Dusk EVM](/learn/deep-dive/dusk-evm) is an OP Stack-based EVM-equivalent execution environment. It lets you deploy Solidity contracts using standard EVM tooling while using DuskDS for settlement and data availability. ## Network Layer: Kadcast -Kadcast is an innovative peer-to-peer protocol used by Dusk to optimize message exchanges between nodes. Unlike the traditional Gossip protocols used by many blockchain protocols, which broadcasts messages to a random set of nodes, Kadcast uses a structured overlay to direct message flow. This drastically reduces network bandwidth and makes latency much more predictable, and at the same time lower compared to Gossip protocols. - -Kadcast is highly resilient to network changes and failures. It dynamically updates routing tables to handle node churn, making it suitable for decentralized environments where network conditions can be unpredictable. Even when nodes fail to forward messages, Kadcast’s built-in fault tolerance ensures alternative paths are used, maintaining reliable message delivery. - -Deep dive into Kadcast implementation +Kadcast is Dusk’s P2P networking layer. It uses a structured overlay (instead of random gossip) to reduce bandwidth and improve latency predictability. ## Genesis Contracts -Dusk contains two fundamental Genesis contracts, which are contracts that are available when the network starts, known as the **stake** and **transfer** contracts. +Dusk ships with two genesis contracts: -The Stake Contract manages the stakes of node [provisioners](/operator/provisioner) (stakers). It tracks active provisioners, records their rewards, and provides functions to stake, unstake, and withdraw rewards. +- **Stake**: tracks provisioners, stakes, rewards, and validator set management. (source) +- **Transfer**: transfers `DUSK` and is the entry point for transaction execution and gas payment. (source) -The Transfer Contract is responsible for the transferring of `DUSK`, regardless of the transaction model used. +For node operators: [Run a provisioner node](/operator/provisioner/). ## Applications -Applications powered by Dusk provide decentralized market infrastructure (DeMI) for regulated finance. While Zedger and Hedger facilitate secure asset lifecycle management, Citadel enables self-sovereign identity (SSI) with selective disclosure. These applications are designed to meet regulatory standards without compromising on decentralization, privacy, or usability. - +On top of the base protocol, Dusk supports application-layer protocols for regulated markets. ### Zedger / Hedger -Zedger is an asset protocol that incorporates a unique hybrid transaction model combining the benefits of both UTXO and account-based transaction models. This model provides the Confidential Security Contract (XSC) functionality necessary for Dusk’s securities-related use-cases among them the full lifecycle management of securities and supporting full regulatory compliance. - -Zedger allows for the digital representation, native issuance and management of securities in a privacy-preserving manner. Issuers of securities are able to issue, manage, and let investors trade securities as XSC tokens It offers built-in support for compliant settlement, redemption of securities, preventing pre-approved users from having more than one account, supports dividend distribution and voting, and can handle capped transfers. Zedger aims to support a range of security types, like stocks, bonds and ETFs. The emphasis on regulatory compliance and privacy ensures that all operations meet the highest standards required by financial authorities and stakeholders. +Zedger and Hedger are protocols for issuing and managing regulated assets with built-in compliance and privacy constraints. -Differently from Zedger, which operated directly on Rusk, Hedger runs on DuskEVM leveraging the EVM equivalency of Dusk’s new execution layer. ZK operations in Hedger are handled via precompiled contracts provided by DuskEVM, mirroring the functionality once exposed through host functions in Rusk. This shift enables significantly easier developer access to privacy-preserving logic, while preserving the regulatory guarantees and auditability required for compliant finance. +- **Zedger** runs natively on DuskDS. +- **Hedger** runs on DuskEVM to offer an EVM-first developer experience. ### Citadel ![Citadel](../../../assets/citadel.gif) -Citadel is a Self-Sovereign Identity (SSI)/Digital Identity (DI) protocol designed for authenticating with third party services while upholding user privacy. With Citadel it’s possible to anonymously prove identity information, like meeting a certain age threshold or living in a certain jurisdiction, without revealing the exact information or revealing more information than is necessary. Given that Citadel is part of the network, it has wide ranging applications for on-chain activity and realizing compliance in regulated financial markets. +Citadel is Dusk’s identity and access layer. It supports selective disclosure so users can prove attributes (e.g. residency, age bracket, accreditation) without revealing more than necessary. [Deep dive into Citadel](/developer/digital-identity/protocol) diff --git a/src/content/docs/learn/guides/duskevm-bridge.md b/src/content/docs/learn/guides/duskevm-bridge.md index 3f8fe84..44150ba 100644 --- a/src/content/docs/learn/guides/duskevm-bridge.md +++ b/src/content/docs/learn/guides/duskevm-bridge.md @@ -3,69 +3,54 @@ 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. +Bridge testnet DUSK from DuskDS to DuskEVM using the official Dusk Web Wallet. Once bridged, DUSK is the native gas token on DuskEVM Testnet. -Once bridged, your DUSK becomes the native gas token on DuskEVM, so you can deploy and interact with smart contracts using standard EVM tooling. +## Fast path -## 1) Prerequisites +1. Get testnet DUSK in the Web Wallet and **unshield** the amount you want to bridge. See: [How to get testnet tokens](/operator/networks#how-to-get-testnet-tokens). +2. Open the Web Wallet (testnet): [apps.testnet.dusk.network/wallet](https://apps.testnet.dusk.network/wallet/) +3. Go to `Dashboard -> Bridge` and connect your Web3 wallet (approve adding/switching to DuskEVM when prompted). +4. Set **From: DuskDS** and **To: DuskEVM**, enter an amount, and send. +5. Track status: + - DuskDS explorer: [apps.testnet.dusk.network/explorer](https://apps.testnet.dusk.network/explorer/) + - DuskEVM explorer: [explorer.testnet.evm.dusk.network](https://explorer.testnet.evm.dusk.network/) -Before you start, make sure you have: +## 1) Prerequisites -- 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 Dusk Web Wallet account with some **testnet DUSK** (and the amount you want to bridge **unshielded**). See: [How to get testnet tokens](/operator/networks#how-to-get-testnet-tokens). - 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: [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/) -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. - -If needed, convert shielded funds to public (unshield) first, using the standard Web Wallet flow. +1. Visit the [Dusk Web Wallet](https://apps.testnet.dusk.network/wallet/). +2. Unlock your wallet. +3. Confirm you have enough **unshielded** DUSK for the bridge amount and fees. ## 3) Connect a Web3 wallet to DuskEVM Testnet -1. In the Web Wallet sidebar, go to Dashboard -> Bridge. -2. If no Web3 wallet is connected yet, you’ll see a button: - > **CONNECT WEB3 WALLET** -3. Click the button. A connect modal opens (via Reown) with wallet options such as MetaMask or WalletConnect. -4. Select your preferred Web3 wallet and approve the connection. -5. When prompted by your Web3 wallet: - - Approve adding DuskEVM as a network (if it’s not already added). - - Approve switching the active network to DuskEVM. -6. After successful connection the Bridge UI becomes active. The bridge now knows: - - Your DuskDS unshielded address (from the web wallet). - - Your EVM address (from the connected Web3 wallet). +1. In the Web Wallet sidebar, go to `Dashboard -> Bridge`. +2. Click **CONNECT WEB3 WALLET** and connect your wallet (MetaMask / WalletConnect, etc.). +3. When prompted by your wallet, approve: + - Adding DuskEVM as a network (if needed). + - Switching to the DuskEVM network. ## 4) Configure the bridge (DuskDS -> DuskEVM) -On the Bridge page you’ll see a three‑step wizard. +On the Bridge page you’ll see a short wizard. ### 4.1 Choose origin and destination networks -In Step 1 of the wizard ("Bridge" screen): - Under **From**, select **DuskDS**. - Under **To**, select **DuskEVM**. -The UI enforces that **From** and **To** can’t be the same, so as soon as you choose `DuskDS` as the origin, `DuskEVM` will be the only valid destination (and vice‑versa). - ### 4.2 Enter the amount -1. In the **Amount** field, enter how much DUSK you want to bridge. -2. The wallet will: - - Show your **DuskDS unshielded balance**. - - Prevent you from spending more than your available balance minus fees. +In the **Amount** field, enter how much DUSK you want to bridge. The wallet will prevent you from spending more than your available balance minus fees. ### 4.3 (Advanced) Adjust gas settings -Because this is a deposit from DuskDS to DuskEVM, you’ll see a Gas Settings panel: - -- Gas limit and gas price are pre‑filled with sensible defaults. -- The estimated Gas fee is shown and will be deducted from your unshielded DUSK balance. -- Advanced users can tweak these values, but for most testnet use‑cases the defaults are recommended. - -If the gas settings are invalid, the Next button will be disabled until you correct them. +If you see a Gas Settings panel, the defaults are usually fine for testnet. ## 5) Review and send the bridge transaction @@ -77,7 +62,6 @@ Here you’ll see: - **From** – your DuskDS unshielded address. - **To** – your EVM address on DuskEVM (from your connected Web3 wallet). - **Gas fee** – shown via the gas fee component. -- **Fee Details** – clarifying that fees are taken from your unshielded balance. Carefully verify: @@ -91,58 +75,28 @@ If everything looks good: 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. +:::note +Under the hood, this is a DuskDS transaction that triggers a deposit into the bridge, which results in funds being credited to your EVM address on DuskEVM. +::: ## 6) Track the bridge & check explorers ### 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. - -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. +Use the "VIEW ON BLOCK EXPLORER" button, or open the [DuskDS Testnet Explorer](https://apps.testnet.dusk.network/explorer/) and search by address/transaction hash. ### 6.2 On DuskEVM Testnet -Once the deposit has been processed by DuskEVM, which can take a couple of minutes, your EVM wallet’s DUSK balance on DuskEVM Testnet will increase. You can review this in the transaction history on your Web3 wallet. - -To inspect this on the explorer: - -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. +Once processed (often a couple of minutes), your EVM wallet’s DUSK balance on DuskEVM Testnet will increase. You can inspect this on the [DuskEVM testnet explorer](https://explorer.testnet.evm.dusk.network/) by searching for your EVM address. ## 7) Interacting with DuskEVM after bridging -Once you have DUSK on DuskEVM Testnet, you can use it just like gas on any EVM chain: - -### 7.1 Use your Web3 wallet normally - -- Keep your Web3 wallet network set to DuskEVM. -- Your bridged DUSK appears as the native gas token. -- You can send DUSK to other EVM addresses on DuskEVM, and approve and interact with DeFi or other dApps that support DuskEVM. - -### 7.2 Deploy and test smart contracts - -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. -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/). - -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. - -### 7.3 Use dApps on DuskEVM +After bridging, you can use DUSK as gas and interact with EVM contracts as usual. -If a dApp supports DuskEVM: +For developers, next steps: -1. Open the dApp in your browser. -2. Ensure your Web3 wallet is connected to **DuskEVM**. -3. Connect the wallet inside the dApp as you would on any other EVM chain. -4. Use your bridged DUSK to: Provide liquidity, trade, interact with protocols. +- [Deploy on DuskEVM](/developer/smart-contracts-dusk-evm/deploy-on-evm/) +- [DuskEVM deep dive](/learn/deep-dive/dusk-evm/) ## 8) (Optional) Withdrawing from DuskEVM back to DuskDS @@ -158,7 +112,7 @@ The same Web Wallet bridge UI also supports DuskEVM -> DuskDS withdrawals: After you submit a withdrawal: - A transaction is sent on DuskEVM calling the standard bridge contract. -- On the DuskDS side, the withdrawal becomes finalizable after a certain number of blocks (the finalization period). +- On the DuskDS side, the withdrawal becomes finalizable after the configured 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. diff --git a/src/content/docs/operator/provisioner.mdx b/src/content/docs/operator/provisioner.mdx index 3f0cf51..9cf1241 100644 --- a/src/content/docs/operator/provisioner.mdx +++ b/src/content/docs/operator/provisioner.mdx @@ -3,9 +3,11 @@ title: Run a provisioner node description: Discover what a Dusk Full Validator Node (Provisioner) is and how to run such a node --- -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. +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +Provisioners are full nodes that participate in consensus. To participate, you stake a **minimum of 1000 DUSK** and run a provisioner node 24/7. -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. +If you only want to stake (without operating infrastructure), start with: [Staking basics](/learn/guides/staking-basics/). ## Provisioner Specifications @@ -16,144 +18,102 @@ The following specifications support Provisioner nodes with limited proving capa | 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. +This is the shortest reliable path: -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 DigitalOcean credit by using [our referral link](https://m.do.co/c/0478e6f591ad). Or a $20 credit for Hetzner if you prefer that service through [our referral link](https://hetzner.cloud/?ref=8gbc6aaxlzXo). +1. Create a server (Ubuntu 24.04). +2. Open ports: `22/tcp` (SSH), `9000/udp` (Kadcast). Optional: `8080/tcp` (HTTP server, mainly for archive/indexer use-cases). +3. Install the node with the official installer. +4. Set up the node wallet and stake. +5. Keep it upgraded and monitored. ## Create a droplet -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). +You can run a provisioner on any VPS/provider as long as it matches the specs above and runs Ubuntu 24.04. -![Create droplet page.](../../../assets/node-guide/create-droplet.png) +If you’re using DigitalOcean, see the optional walkthrough below. -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. +
+ DigitalOcean walkthrough (optional) -Under _Choose an image_, pick Ubuntu version 24.04 (LTS) x64. +DO uses droplets (Linux VMs). When you’re logged in, go to _Droplets_ and click _Create Droplet_. -![Select region and image for the droplet.](../../../assets/node-guide/region-image-droplet.png) +![Create droplet page.](../../../assets/node-guide/create-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. +1. Choose a region. +2. Choose image: **Ubuntu 24.04 (LTS) x64**. +3. Choose size: at least the [Provisioner Specifications](/operator/provisioner#provisioner-specifications). +4. Prefer SSH keys over passwords. +![Select region and image for the droplet.](../../../assets/node-guide/region-image-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) - -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) - -DO will now set the droplet up for you. This can take a minute: - ![Droplet being created.](../../../assets/node-guide/droplet-creation.png) +
## Configure Firewall -The Rusk node uses the Kadcast protocol to communicate messages between nodes on the network. This protocol uses UDP and requires custom port forwarding. Depending on your hosting provider or local setup, you'll need to enable the following ports: -- **SSH port**: Default is `22` for remote access -- `9000/udp`: For Kadcast (used for consensus messages) -- (Optional) `8080/tcp`: For the HTTP server (primarily used for archive nodes) - -### Firewall Group +Enable the required ports: -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) +- `22/tcp` (SSH) +- `9000/udp` (Kadcast; consensus networking) +- Optional: `8080/tcp` (HTTP server; mainly for archive/indexer use-cases) -Give the firewall a name, open UDP under port 9000 (optionally TCP under 8080 too). Leave all the Outbound rules as they are. - -Apply the rules to the node droplet you made. - -Your firewall should look as follows: - -![Configure firewall.](../../../assets/node-guide/configure-firewall.png) +If you manage a local firewall, here’s a minimal `ufw` example: -Click on _Create Firewall_ to apply this firewall to your node's droplet. - -### Local Firewall - -For local setups, you can use tools like `ufw`, `iptables`, or `firewalld`. Although it's not strictly needed to setup a local firewall if you use firewall groups, it's still recommended to do so with "layered security" in mind. - -Here's an example setup using `ufw`: ```bash -# Allow SSH (default port 22) with rate limiting sudo ufw limit ssh -# Allow Kadcast UDP traffic sudo ufw allow 9000/udp -# Enable the firewall sudo ufw enable ``` -For non-default SSH ports, replace `ssh` with the specific port number. Adjust commands if using other firewall tools. - -## Install Rusk +
+ DigitalOcean firewall group (optional) -Navigate back to your [droplets overview](https://cloud.digitalocean.com/droplets) and select your droplet: +Create a firewall and open UDP `9000` (and optionally TCP `8080`). -![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) +![Create firewall page.](../../../assets/node-guide/create-firewall.png) +![Configure firewall.](../../../assets/node-guide/configure-firewall.png) +
-A terminal should pop-up and connect you to your Droplet +## Install Rusk -![Droplet terminal.](../../../assets/node-guide/droplet-terminal.png) +SSH into your server (or use your provider’s web console). -### (Optional) User and Group Permissions +### (Optional) Security baseline (recommended) -Before using the node installer, we recommend setting up a secure, dedicated non-root user account. This is not strictly necessary, but a good security practice. If you haven't created such a user yet, follow these steps: +Run the node under a dedicated non-root user and use SSH keys (not passwords). -#### Step 1: Create a Dedicated Group & User +
+ Create a dedicated user (optional) -Create a new non-root user (e.g., `duskadmin`), add them to the `dusk` group and set a password for the new user: ```sh sudo groupadd --system dusk sudo useradd -m -G dusk -s /bin/bash duskadmin sudo passwd duskadmin ``` -#### Step 2: Set Up SSH Access - -Ensure the new user has access to your public SSH keys for secure login. Add your public key directly to the new user's `authorized_keys` file: -1. Edit or create the `authorized_keys` file for the new user: ```sh mkdir -p /home/duskadmin/.ssh sudo nano /home/duskadmin/.ssh/authorized_keys ``` -2. Paste your public SSH key (e.g., starting with `ssh-rsa` or `ssh-ed25519`) -3. Save and set proper permissions: ```sh sudo chmod 700 /home/duskadmin/.ssh sudo chmod 600 /home/duskadmin/.ssh/authorized_keys sudo chown -R duskadmin:dusk /home/duskadmin/.ssh ``` -#### Step 3: Add `duskadmin` to the `sudo` Group - -If not already done, log in as `root` or a user with sufficient privileges and add `duskadmin` to the `sudo` group: ```sh sudo usermod -aG sudo duskadmin ``` -Log out from you node for the group changes to take effect. +
-#### Step 4: Verify Access - -Test SSH access to the new user account by connecting to the node with the new account: -```sh -ssh duskadmin@ -``` - -### Node Installer +### Install with the node installer We've created an easy to use [node installer](https://github.com/dusk-network/node-installer). This installer will set up Rusk as a service on your droplet, preconfigure parts of the node, and provide a couple of helper scripts. -Install Rusk by pasting the following command in your droplet terminal: - -import { Tabs, TabItem } from '@astrojs/starlight/components'; +Install Rusk by pasting the following command on your server: @@ -185,7 +145,8 @@ You should see the latest version number confirming a successful installation. ## Configure Rusk -Now that you have setup rusk, it's time to setup your wallet to finally start participating in consensus +Now set up the node wallet and stake so you can participate 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. +Follow: [Node wallet setup](/operator/guides/node-wallet-setup/). +For next steps, see: [Maintenance & monitoring](/operator/maintenance-monitoring/) and [Upgrade your node](/operator/guides/upgrade-node/).