diff --git a/astro.config.js b/astro.config.js index 50d42fef..c62d50fe 100644 --- a/astro.config.js +++ b/astro.config.js @@ -32,6 +32,8 @@ export default defineConfig({ '/developer/integrations/hashing-algorithms': '/developer/integrations/reference', '/developer/integrations/addresses': '/developer/integrations/reference', '/developer/smart-contract/hyperstaking_tech': '/learn/hyperstaking', + '/learn/deep-dive/dusk-evm': '/learn/dusk-evm', + '/developer/smart-contracts-dusk-evm/deploy-on-evm': '/developer/duskevm/quickstart', }, integrations: [ starlight({ diff --git a/src/content/docs/developer/duskevm/quickstart.md b/src/content/docs/developer/duskevm/quickstart.md new file mode 100644 index 00000000..0d64cf3d --- /dev/null +++ b/src/content/docs/developer/duskevm/quickstart.md @@ -0,0 +1,106 @@ +--- +title: DuskEVM quickstart +description: Fund a testnet account and deploy a Solidity contract to DuskEVM. +--- + +Deploy a Solidity contract to DuskEVM Testnet with Foundry or Hardhat. DuskEVM uses the standard Ethereum JSON-RPC interface, so the workflow is the same one used for other OP Stack networks. + +## Testnet + +| Setting | Value | +|---|---| +| Chain ID | `745` | +| RPC | `https://rpc.testnet.evm.dusk.network` | +| Gas token | DUSK | +| Explorer | `https://explorer.testnet.evm.dusk.network` | + +Confirm the RPC before signing: + +```bash +cast chain-id --rpc-url https://rpc.testnet.evm.dusk.network + +# 745 +``` + +## 1. Fund the deployer + +Create a dedicated EVM deployment account, then [bridge testnet DUSK to it](/learn/guides/duskevm-bridge/). Keep enough DUSK in the account to pay deployment gas. + +Use an encrypted keystore or hardware signer. Do not place raw private keys in source files or shell history. + +## 2. Deploy + +### Foundry + +Initialize a project and import the deployment key into Foundry's encrypted keystore: + +```bash +forge init duskevm-quickstart +cd duskevm-quickstart +cast wallet import duskevm-testnet-deployer --interactive +``` + +Deploy the example `Counter` contract created by `forge init`: + +```bash +forge create src/Counter.sol:Counter \ + --rpc-url https://rpc.testnet.evm.dusk.network \ + --account duskevm-testnet-deployer \ + --broadcast +``` + +### Hardhat 3 + +Initialize a Hardhat project with the viem toolbox, then add DuskEVM Testnet to `hardhat.config.ts`: + +```ts title="hardhat.config.ts" +import hardhatToolboxViemPlugin from "@nomicfoundation/hardhat-toolbox-viem"; +import { configVariable, defineConfig } from "hardhat/config"; + +export default defineConfig({ + plugins: [hardhatToolboxViemPlugin], + solidity: { version: "0.8.28" }, + networks: { + duskEvmTestnet: { + type: "http", + chainType: "op", + chainId: 745, + url: configVariable("DUSKEVM_TESTNET_RPC_URL"), + accounts: [configVariable("DUSKEVM_TESTNET_PRIVATE_KEY")], + }, + }, +}); +``` + +Store the configuration values in Hardhat's encrypted keystore: + +```bash +npx hardhat keystore set DUSKEVM_TESTNET_RPC_URL +npx hardhat keystore set DUSKEVM_TESTNET_PRIVATE_KEY +``` + +Deploy the example Ignition module created by `npx hardhat --init`: + +```bash +npx hardhat ignition deploy ignition/modules/Counter.ts \ + --network duskEvmTestnet +``` + +## 3. Confirm the deployment + +Both tools print the deployed contract address. Confirm that the address contains bytecode: + +```bash +cast code \ + --rpc-url https://rpc.testnet.evm.dusk.network +``` + +The result should be longer than `0x`. Inspect the deployment transaction and contract in the [DuskEVM testnet explorer](https://explorer.testnet.evm.dusk.network/). + +## 4. Verify the source + +Open the contract in Blockscout and select **Verify & Publish**. Use the compiler version, optimizer settings, source files, and constructor arguments from the deployment build. + +Blockscout also supports automated verification from [Foundry](https://docs.blockscout.com/devs/verification/foundry-verification) and [Hardhat](https://docs.blockscout.com/devs/verification/hardhat-verification-plugin). + +Before deploying to mainnet, review the [DuskEVM network and compatibility reference](/developer/duskevm/reference/). diff --git a/src/content/docs/developer/duskevm/reference.md b/src/content/docs/developer/duskevm/reference.md new file mode 100644 index 00000000..bab3c1ce --- /dev/null +++ b/src/content/docs/developer/duskevm/reference.md @@ -0,0 +1,68 @@ +--- +title: DuskEVM reference +description: Network configuration, transaction behavior, fees, finality, and EVM compatibility notes for DuskEVM. +--- + +## Networks + +| Field | Mainnet | Testnet | Devnet | +|---|---|---|---| +| Chain ID | `744` | `745` | `310` | +| Gas token | DUSK (18 decimals) | DUSK (18 decimals) | DUSK (18 decimals) | +| HTTPS RPC | `https://rpc.evm.dusk.network` | `https://rpc.testnet.evm.dusk.network` | `https://rpc.devnet.evm.dusk.network` | +| WSS RPC | `wss://wss.evm.dusk.network` | `wss://wss.testnet.evm.dusk.network` | `wss://wss.devnet.evm.dusk.network` | +| Explorer | `https://explorer.evm.dusk.network` | `https://explorer.testnet.evm.dusk.network` | `https://explorer.devnet.evm.dusk.network` | +| Target block time | ~2 seconds | ~2 seconds | ~2 seconds | + +Use `eth_chainId` before signing or submitting a transaction. Mainnet returns `0x2e8`, testnet returns `0x2e9`, and devnet returns `0x136`. + +## Transaction handling + +DuskEVM uses centralized sequencing. Transactions are submitted to the sequencer instead of broadcast through a public peer-to-peer mempool. + +Applications should: + +- use the submitted transaction hash to track pending transactions; +- support nonce-based replacement without assuming public mempool visibility; and +- treat a receipt as inclusion, not as proof that every settlement or bridge stage has completed. + +## Fees + +DUSK pays for DuskEVM transactions. A transaction normally includes: + +- an L2 execution fee; and +- a data-availability fee for publishing its share of batch data to DuskDS. + +Use `eth_estimateGas` to estimate the execution limit and EIP-1559 fee fields when constructing transactions. Wallets and standard EVM libraries obtain these values through JSON-RPC. + +## Inclusion and finality + +An included DuskEVM transaction can be visible before its data and state have completed DuskDS settlement. + +- **Deposits** are credited on DuskEVM after the DuskDS deposit is processed. +- **Withdrawals** require proof, network finality checks, and a separate DuskDS finalization transaction. + +Use the bridge, wallet, or protocol contract status instead of calculating withdrawal readiness from time alone. + +## EVM behavior + +Most Solidity contracts require no Dusk-specific changes. Account for these OP Stack behaviors where relevant: + +| Solidity value | Behavior | +|---|---| +| `block.coinbase` | Returns the configured sequencer fee recipient. Do not assume it changes between blocks. | +| `block.prevrandao` | Reflects rollup origin metadata. It is not a source of secure or unbiased randomness. | +| `tx.origin` in deposits | Contract-originated DuskDS to DuskEVM deposits use OP address aliasing. Use cross-domain messaging when the original sender identity matters. | + +## Contract verification + +DuskEVM explorers use Blockscout. Verify with the exact compiler version, EVM version, optimizer settings, source files, and constructor arguments used for deployment. + +- [Foundry verification](https://docs.blockscout.com/devs/verification/foundry-verification) +- [Hardhat verification](https://docs.blockscout.com/devs/verification/hardhat-verification-plugin) + +## Related guides + +- [DuskEVM quickstart](/developer/duskevm/quickstart/) +- [Bridge DUSK](/learn/guides/duskevm-bridge/) +- [DuskEVM overview](/learn/dusk-evm/) diff --git a/src/content/docs/developer/overview.mdx b/src/content/docs/developer/overview.mdx index 7bfacc02..4806ed37 100644 --- a/src/content/docs/developer/overview.mdx +++ b/src/content/docs/developer/overview.mdx @@ -20,7 +20,7 @@ As a builder, choose the path based on what your product needs and which tooling Hardhat -- Foundry - -## 2) Fund your account with DUSK - -Ensure your wallet is connected to the DuskEVM network and has been funded with some DUSK. - -## 3) Configure your environment - -Before deploying, make sure you use the correct configuration for DuskEVM deployment, including the correct chain ID and RPC endpoints. - -If using Foundry, add DuskEVM's information to your `foundry.toml`: - -```toml -[rpc_endpoints] -dusk_evm_mainnet = "https://rpc.evm.dusk.network" -dusk_evm_testnet = "https://rpc.testnet.evm.dusk.network" -``` - -If using Hardhat, you can add DuskEVM in your `hardhat.config.js`: - -```js -module.exports = { - networks: { - duskEvmMainnet: { - url: "https://rpc.evm.dusk.network", - chainId: 744, - }, - duskEvmTestnet: { - url: "https://rpc.testnet.evm.dusk.network", - chainId: 745, - } - } -}; -``` - -## 4) Deployment - - -If using Foundry, navigate to your project’s directory and launch: - -``` -forge create src/{YourContract}.sol:{ContractName} --rpc-url dusk_evm_testnet --private-key {YourPrivateKey} -``` - -If using Hardhat, add a deploy script in the scripts folder (e.g., add `scripts/deploy.js`), and then run it (e.g., with `npx hardhat run scripts/deploy.js --network duskEVM`). - -## Further Resources - -For full deployment workflows and advanced usage, refer to the official documentation of your preferred tool: - -- Hardhat documentation -- Foundry documentation diff --git a/src/content/docs/developer/smart-contracts-duskds.md b/src/content/docs/developer/smart-contracts-duskds.md index 73522926..dbed7ac0 100644 --- a/src/content/docs/developer/smart-contracts-duskds.md +++ b/src/content/docs/developer/smart-contracts-duskds.md @@ -6,7 +6,7 @@ description: Build Rust/WASM smart contracts on DuskDS using the Forge framework Dusk offers two paths for smart contract development: - **DuskDS** (this page) - general-purpose Rust/WASM contracts on Dusk's native execution layer, with access to native transaction models, privacy-aware flows, and the full power of Rust's ecosystem -- **[DuskEVM](/developer/smart-contracts-dusk-evm/deploy-on-evm)** - An Optimism-based EVM application layer for Solidity/Vyper contracts using familiar tooling (Hardhat, Foundry) +- **[DuskEVM](/developer/duskevm/quickstart/)** - An Optimism-based EVM application layer for Solidity/Vyper contracts using familiar tooling (Hardhat, Foundry) Choose DuskDS when you want to build directly with Dusk's native primitives: Rust/WASM execution, protocol-level assets, custom market logic, public and shielded transaction models, or privacy-aware compliance flows. Choose DuskEVM when you want Solidity, EVM wallets, and the broader Ethereum tooling ecosystem. diff --git a/src/content/docs/learn/core-components.md b/src/content/docs/learn/core-components.md index 184dce75..e4d2d926 100644 --- a/src/content/docs/learn/core-components.md +++ b/src/content/docs/learn/core-components.md @@ -12,7 +12,7 @@ At a high level: | **DuskDS** | Dusk L1: settlement, consensus, data availability, and native transaction models | [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/) | +| **DuskEVM** | OP Stack-based EVM execution environment | [DuskEVM overview](/learn/dusk-evm/), [DuskEVM quickstart](/developer/duskevm/quickstart/) | | **Citadel** | Identity and access primitives (selective disclosure) | [Digital Identity protocol](/developer/digital-identity/protocol/) | ## DuskDS @@ -53,7 +53,7 @@ Dusk supports multiple execution environments on top of DuskDS. Each environment [DuskVM](/learn/deep-dive/dusk-vm) is a WASM execution environment built around Wasmtime. It is optimized for Dusk-native smart contracts that need direct access to native assets, custom execution, privacy, or zero-knowledge capabilities. ### DuskEVM -[DuskEVM](/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. +[DuskEVM](/learn/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 diff --git a/src/content/docs/learn/deep-dive/dusk-evm.md b/src/content/docs/learn/deep-dive/dusk-evm.md deleted file mode 100644 index e07deed2..00000000 --- a/src/content/docs/learn/deep-dive/dusk-evm.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: DuskEVM -description: DuskEVM is an OP Stack-based EVM execution environment that uses DuskDS for settlement and data availability. ---- - -DuskEVM is an EVM-equivalent execution environment built on the OP Stack that uses DuskDS for settlement and data availability. - -Use DuskEVM when your application benefits from Solidity, Ethereum-compatible tooling, EVM wallets, and existing smart contract infrastructure. - -Use native Dusk development instead when your application should be built directly against Dusk's own execution model: Rust/WASM contracts, native transaction models, protocol-level assets, custom market logic, or privacy and zero-knowledge capabilities. For that path, see [DuskVM](/learn/deep-dive/dusk-vm/) and [Smart Contracts on DuskDS](/developer/smart-contracts-duskds/). - -## Where DuskEVM fits - -DuskEVM is the EVM execution path in the Dusk stack: - -- **Developers** use familiar Solidity tooling. -- **Applications** can inherit settlement and data availability from DuskDS. -- **Users** pay gas in DUSK on DuskEVM. -- **Privacy-sensitive flows** can use additional Dusk tooling such as Hedger where appropriate. - -For the broader architecture, see [Core Components](/learn/core-components). - -## Network Information - -| Field | **Mainnet** | **Testnet** | **Devnet** | -|---|---|---|---| -| **Chain name** | DuskEVM | DuskEVM Testnet | DuskEVM Devnet | -| **Chain ID** | 744 | 745 | 310 | -| **Native token** | DUSK (18) | DUSK (18) | DUSK (18) | -| **RPC (HTTPS)** | `https://rpc.evm.dusk.network` | `https://rpc.testnet.evm.dusk.network` | `https://rpc.devnet.evm.dusk.network` | -| **RPC (WSS)** | `wss://wss.evm.dusk.network` | `wss://wss.testnet.evm.dusk.network` | `wss://wss.devnet.evm.dusk.network` | -| **Explorer** | `https://explorer.evm.dusk.network/` | `https://explorer.testnet.evm.dusk.network/` | `https://explorer.devnet.evm.dusk.network/` | -| **Avg. block time** | ~2s | ~2s | ~2s | - -## Quick Checks (RPC) - -Confirm you are connected to the right chain: - -```bash -curl -sS -H 'content-type: application/json' \ - -d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}' \ - https://rpc.testnet.evm.dusk.network - -# -> {"jsonrpc":"2.0","id":1,"result":"0x2e9"} (745) -``` - -## Common Workflows - -- Fund an EVM wallet on testnet (bridge DUSK from DuskDS): [Bridge DUSK from DuskDS to DuskEVM Testnet](/learn/guides/duskevm-bridge/) -- Deploy a Solidity contract: [Deploy on DuskEVM](/developer/smart-contracts-dusk-evm/deploy-on-evm/) - -## How It Works (High-Level) - -- The sequencer executes EVM transactions (OP Stack / `op-geth`). -- The batcher posts transaction data to DuskDS (as blobs). -- The proposer posts state commitments that reference executed batches. - -## Fees - -On OP-Stack chains like DuskEVM, the fee you pay typically includes: - -- An L2 execution fee (EIP-1559 style). -- A data-availability fee for posting batch data to DuskDS. - -Wallets and SDKs usually estimate both automatically. If you’re doing your own fee logic, treat total cost as `execution + data`. - -## Runtime Differences - -Most EVM behavior is identical, but a few fields behave differently due to the OP Stack / bridge model: - -| Opcode | Solidity Equivalent | Behavior | -|-------------|---------------------|----------| -| `COINBASE` | `block.coinbase` | Address of the sequencer fee wallet. | -| `PREVRANDAO`| `block.prevrandao` | PREVRANDAO derived from the DuskDS origin block. | -| `ORIGIN` | `tx.origin` | For bridge deposits (**DuskDS ⇒ DuskEVM**), `tx.origin` is set to the aliased address of the originator. | - -:::note -DuskEVM currently has no public mempool (sequencer only). -::: - -## Verify a Contract (Blockscout) - -DuskEVM uses Blockscout as its explorer. Choose the workflow that matches your toolchain: - -- Blockscout UI (Verify & Publish): docs.blockscout.com/devs/verification -- Hardhat plugin: docs.blockscout.com/devs/verification/hardhat-verification-plugin -- Foundry (Forge): docs.blockscout.com/devs/verification/foundry-verification diff --git a/src/content/docs/learn/deep-dive/dusk-vm.md b/src/content/docs/learn/deep-dive/dusk-vm.md index 9f9db642..d136df6b 100644 --- a/src/content/docs/learn/deep-dive/dusk-vm.md +++ b/src/content/docs/learn/deep-dive/dusk-vm.md @@ -10,7 +10,7 @@ description: Learn about DuskVM, the Wasmtime-based VM that executes native smar Use DuskVM when your application should run as a native Dusk contract: protocol-level assets, Rust/WASM contracts, custom execution, market logic, privacy-aware flows, or zero-knowledge capabilities close to the settlement layer. -Use DuskEVM instead when your application is designed around Solidity, EVM wallets, and Ethereum-compatible tooling. DuskVM is closer to Dusk's native model; DuskEVM is closer to the Ethereum developer ecosystem. See [DuskEVM](/learn/deep-dive/dusk-evm). +Use DuskEVM instead when your application is designed around Solidity, EVM wallets, and Ethereum-compatible tooling. DuskVM is closer to Dusk's native model; DuskEVM is closer to the Ethereum developer ecosystem. See [DuskEVM](/learn/dusk-evm/). ## Where DuskVM fits diff --git a/src/content/docs/learn/dusk-evm.md b/src/content/docs/learn/dusk-evm.md new file mode 100644 index 00000000..b106b604 --- /dev/null +++ b/src/content/docs/learn/dusk-evm.md @@ -0,0 +1,42 @@ +--- +title: DuskEVM +description: Build Ethereum-compatible applications on an execution layer settled by DuskDS. +--- + +DuskEVM brings Solidity, EVM wallets, and Ethereum tooling to Dusk. Existing EVM applications can target DuskEVM with familiar contracts and workflows while using DUSK for gas and DuskDS for settlement and data availability. + +## Why DuskEVM + +- **Start with the EVM stack.** Use Solidity or Vyper with Foundry, Hardhat, viem, ethers, and standard EVM wallets. +- **Use DUSK natively.** DUSK pays for execution and moves between DuskDS and DuskEVM through the bridge. +- **Settle on DuskDS.** Batches and state commitments anchor DuskEVM activity to Dusk's consensus and data-availability layer. +- **Reach the wider Dusk stack.** EVM applications can connect to Dusk-native assets, infrastructure, and privacy-oriented workflows as those integrations require. + +## How it fits + +| Component | Role | +|---|---| +| **DuskDS** | Consensus, settlement, and data availability | +| **DuskEVM** | Ethereum-compatible smart contract execution | +| **Bridge** | Moves DUSK and messages between both environments | + +A DuskEVM transaction follows a rollup lifecycle: + +1. The transaction is submitted to the DuskEVM sequencer. +2. The execution layer includes it in an L2 block. +3. The batcher publishes the transaction data to DuskDS. +4. State commitments and fault proofs connect the resulting state to DuskDS settlement. + +Transaction inclusion is fast, but inclusion and settlement are different stages. Applications that move value between DuskEVM and DuskDS should use protocol or wallet status rather than infer finality from elapsed time. + +## Choose an execution environment + +Choose **DuskEVM** for Solidity applications, EVM wallets, existing Ethereum libraries, and EVM infrastructure. + +Choose **native Dusk development** for Rust/WASM contracts, native transaction models, protocol-level assets, or direct use of Dusk's privacy and zero-knowledge capabilities. See [DuskVM](/learn/deep-dive/dusk-vm/) and [Smart Contracts on DuskDS](/developer/smart-contracts-duskds/). + +## Start here + +- [Deploy a contract with the DuskEVM quickstart](/developer/duskevm/quickstart/) +- [Review networks and EVM behavior](/developer/duskevm/reference/) +- [Bridge DUSK between DuskDS and DuskEVM](/learn/guides/duskevm-bridge/) diff --git a/src/content/docs/learn/glossary.md b/src/content/docs/learn/glossary.md index b6ca917a..a2fb35f4 100644 --- a/src/content/docs/learn/glossary.md +++ b/src/content/docs/learn/glossary.md @@ -31,7 +31,7 @@ DuskDS is the settlement layer of the Dusk architecture: consensus, data availab #### DuskEVM -[DuskEVM](/learn/deep-dive/dusk-evm) is an EVM execution environment that uses DuskDS as its settlement and data availability layer. +[DuskEVM](/learn/dusk-evm/) is an EVM execution environment that uses DuskDS as its settlement and data availability layer. #### DuskVM diff --git a/src/content/docs/learn/guides/bep20-bridge.md b/src/content/docs/learn/guides/bep20-bridge.md index 9f595a03..330fb68c 100644 --- a/src/content/docs/learn/guides/bep20-bridge.md +++ b/src/content/docs/learn/guides/bep20-bridge.md @@ -5,7 +5,7 @@ description: How to bridge your native DUSK tokens to BEP20 DUSK on Binance Smar This guide explains how to bridge **native DUSK** (Dusk mainnet) to **BEP20 DUSK** on Binance Smart Chain (BSC) using the [Web Wallet](https://apps.dusk.network/wallet/). -When bridging, your native DUSK tokens are locked on the Dusk network. Once locked, a mint operation is initiated on Binance Smart Chain, issuing an equivalent amount of BEP20 DUSK to your specified address. The full bridging process typically completes within 15 minutes. +When bridging, your native DUSK tokens are locked on the Dusk network. Once locked, a mint operation is initiated on Binance Smart Chain, issuing an equivalent amount of BEP20 DUSK to your specified address. The full bridging process typically takes around one hour. :::note Want to **bridge from BEP20 DUSK to native DUSK** instead? Check our [Migration Guide](/learn/guides/mainnet-migration/) for the complete walkthrough. @@ -28,7 +28,7 @@ The BSC address is provided in the **memo** field. If you omit the memo or provi ## Expected time and fees -- **Time**: typically ~15 minutes. +- **Time**: typically around one hour. - **Fees**: the bridge charges a flat **1 DUSK** fee per transaction (your minted amount is `sent - 1 DUSK`). ## Steps @@ -49,7 +49,7 @@ Your DUSK will be locked on the Dusk network, and an equivalent amount will be m ## FAQ **How long does the bridge process take?** -Typically within 15 minutes. Network congestion or confirmations may slightly affect the timing. +Typically around one hour. Network congestion and confirmation times can affect the timing. **Where do the BEP20 tokens go?** They are sent to the EVM address specified in the memo field. @@ -65,6 +65,6 @@ Yes, the bridge charges a flat fee of 1 DUSK per transaction. Your bridged amoun ## Troubleshooting -- **Nothing arrived on BSC after ~15 minutes**: confirm your Dusk transfer succeeded and double-check the memo contains the correct `0x...` address. +- **Nothing arrived on BSC after around one hour**: confirm your Dusk transfer succeeded and double-check the memo contains the correct `0x...` address. - **I used the wrong memo address**: the bridge can’t mint to an unknown target. This is usually not reversible. - **I bridged to an exchange address**: only do this if the exchange explicitly supports BEP20 DUSK deposits and you’re sure the memo address is correct. diff --git a/src/content/docs/learn/guides/duskevm-bridge.md b/src/content/docs/learn/guides/duskevm-bridge.md index b89b4109..4a2228b9 100644 --- a/src/content/docs/learn/guides/duskevm-bridge.md +++ b/src/content/docs/learn/guides/duskevm-bridge.md @@ -1,118 +1,124 @@ --- -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. +title: Bridge DUSK between DuskDS and DuskEVM Testnet +description: Use the Dusk Web Wallet to move testnet DUSK between DuskDS and DuskEVM. --- -Bridge testnet DUSK (nDUSK) from DuskDS to DuskEVM using the official Dusk Web Wallet. Once bridged, DUSK is the native gas token on DuskEVM Testnet. +The Dusk bridge moves DUSK between DuskDS and DuskEVM while keeping one native asset across both environments. On DuskEVM, the bridged DUSK is available in your EVM account and is used to pay gas. -## Fast path +This guide uses testnet DUSK, which has no real-world value, and the testnet Web Wallet. -1. Get testnet DUSK (nDUSK) 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 -## 1) Prerequisites +You need: -- A Dusk Web Wallet account with some **testnet DUSK (nDUSK)** (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: [DuskEVM deep dive](/learn/deep-dive/dusk-evm/) and [Deploy on DuskEVM](/developer/smart-contracts-dusk-evm/deploy-on-evm/). +- a Dusk Web Wallet account with unshielded testnet DUSK for deposits and withdrawal actions on DuskDS; +- an EVM wallet, such as MetaMask, that supports adding a custom network; and +- enough DUSK in the source account to cover the bridge amount and its transaction fee. -## 2) Open the Web Wallet on DuskDS testnet +Request DUSK from the [testnet faucet](/operator/networks#how-to-get-testnet-tokens), then unshield the amount you want to bridge. -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. +## Deposit into DuskEVM -## 3) Connect a Web3 wallet to DuskEVM Testnet +### 1. Open the bridge -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. +1. Open the [testnet Web Wallet](https://apps.testnet.dusk.network/wallet/) and unlock your account. +2. Go to `Dashboard -> Bridge`. +3. Connect your EVM wallet. +4. Approve adding or switching to DuskEVM Testnet when your EVM wallet asks. -## 4) Configure the bridge (DuskDS -> DuskEVM) +Your wallet should be connected to: -On the Bridge page you’ll see a short wizard. +| Setting | Value | +|---|---| +| Network | DuskEVM Testnet | +| Chain ID | `745` | +| RPC | `https://rpc.testnet.evm.dusk.network` | +| Currency symbol | `DUSK` | -### 4.1 Choose origin and destination networks +### 2. Configure the transfer -- Under **From**, select **DuskDS**. -- Under **To**, select **DuskEVM**. +Set: -### 4.2 Enter the amount +- **From:** DuskDS +- **To:** DuskEVM +- **Amount:** the amount of testnet DUSK to deposit -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. +The destination is the address currently selected in your connected EVM wallet. Check the full address before continuing; an EVM transaction cannot correct a deposit sent to the wrong account. -### 4.3 (Advanced) Adjust gas settings +### 3. Review and send -If you see a Gas Settings panel, the defaults are usually fine for testnet. +On the review screen, confirm: -## 5) Review and send the bridge transaction +- the direction is DuskDS to DuskEVM; +- the DuskDS source account and EVM destination are correct; +- the amount and fee are acceptable. -Click Next to move to Step 2 of the wizard (review screen). +Send the transaction and keep the status screen open until the wallet has recorded it. The originating transaction can also be inspected in the [DuskDS testnet explorer](https://apps.testnet.dusk.network/explorer/). -Here you’ll see: +### 4. Confirm the deposit -- **Amount** – the DUSK amount that will be bridged. -- **From** – your DuskDS unshielded address. -- **To** – your EVM address on DuskEVM (from your connected Web3 wallet). -- **Gas fee** – shown via the gas fee component. +After the deposit is processed, the balance of the connected EVM account increases on DuskEVM Testnet. Check it in your EVM wallet or search for the address in the [DuskEVM testnet explorer](https://explorer.testnet.evm.dusk.network/). -Carefully verify: +The DuskDS transaction and the resulting DuskEVM credit happen on different layers, so they do not necessarily appear at the same moment. -- The **direction** is **From: DuskDS** -> **To: DuskEVM**. -- The **destination address** matches the EVM address you expect. -- The **amount** is correct. +## Withdraw to DuskDS -If everything looks good: +A withdrawal returns DUSK from your EVM account to DuskDS. Unlike a deposit, it requires three on-chain actions: initiate the withdrawal on DuskEVM, prove it on DuskDS, and finalize it on DuskDS. -1. Click SEND. -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. +### 1. Submit the withdrawal + +1. Open `Dashboard -> Bridge` in the testnet Web Wallet. +2. Connect the EVM wallet that holds the DUSK. +3. Set **From** to DuskEVM and **To** to DuskDS. +4. Enter the amount, review the destination DuskDS account, and send. + +The first transaction is submitted on DuskEVM. Keep enough DUSK in the EVM account to pay its gas fee, and retain the withdrawal transaction hash. + +### 2. Check the withdrawal status + +Open **Withdrawal status** from the bridge. The latest withdrawal made in the current browser is filled in automatically. Otherwise, paste the DuskEVM withdrawal transaction hash and select **Check status**. + +The first status is normally **Waiting for output proposal**. No action is required until the network has published an output that covers the withdrawal. + +### 3. Prove on DuskDS + +When the status changes to **Ready to prove**, select **Prove withdrawal** and confirm the DuskDS transaction in the Web Wallet. + +After the proof is submitted, the status changes to **Waiting to finalize** while the proof maturity delay and dispute-game checks complete. :::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. +Proof and finalization readiness are determined by network state, not by a timer alone. Use **Check status** rather than calculating readiness from elapsed time. ::: -## 6) Track the bridge & check explorers +### 4. Finalize on DuskDS + +When the status changes to **Ready to finalize**, select **Finalize withdrawal** and confirm the DuskDS transaction that releases the DUSK to your DuskDS account. + +Proving and finalizing are separate DuskDS transactions. Keep enough unshielded DUSK on DuskDS to pay both fees. After finalization is confirmed, the returned amount appears in the destination account. -### 6.1 On DuskDS +## Troubleshooting -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. +**The EVM wallet shows the wrong network** -### 6.2 On DuskEVM Testnet +Switch to DuskEVM Testnet and confirm that the chain ID is `745` before retrying. -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. +**The DuskDS deposit succeeded but the EVM balance has not changed** -## 7) Interacting with DuskEVM after bridging +The deposit may still be processing between layers. Check the originating DuskDS transaction first, then the destination address in the DuskEVM explorer. -After bridging, you can use DUSK as gas and interact with EVM contracts as usual. +**A withdrawal is still pending** -For developers, next steps: +Pending does not mean failed. Open **Withdrawal status** and select **Check status**. Wait if the status reports **Waiting for output proposal**, **Proof submitted**, or **Waiting to finalize**. -- [Deploy on DuskEVM](/developer/smart-contracts-dusk-evm/deploy-on-evm/) -- [DuskEVM deep dive](/learn/deep-dive/dusk-evm/) +**The proof cannot be submitted** -## 8) (Optional) Withdrawing from DuskEVM back to DuskDS +Confirm that the status is **Ready to prove**, the correct DuskDS account is unlocked, and the account has enough unshielded DUSK for the proof transaction fee. -The same Web Wallet bridge UI also supports DuskEVM -> DuskDS withdrawals: +**Finalization cannot be submitted** -1. Go to Dashboard -> Bridge in the Web Wallet. -2. Make sure your Web3 wallet is connected to DuskEVM. -3. In the Bridge wizard: - - Set **From** to **DuskEVM**. - - Set **To** to **DuskDS**. -4. Enter the amount and follow the same review/send flow. +Confirm that the status is **Ready to finalize**, the correct DuskDS account is unlocked, and the account has enough unshielded DUSK for the finalization transaction fee. If the Web Wallet offers **Prove withdrawal** again, submit the newer proof before trying to finalize. -After you submit a withdrawal: +## Next steps -- A transaction is sent on DuskEVM calling the standard bridge contract. -- 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. +- [Understand how DuskEVM works](/learn/dusk-evm/) +- [Deploy a contract on DuskEVM](/developer/duskevm/quickstart/) diff --git a/src/content/docs/learn/guides/mainnet-migration.md b/src/content/docs/learn/guides/mainnet-migration.md index 3723ad47..fdbb29a6 100644 --- a/src/content/docs/learn/guides/mainnet-migration.md +++ b/src/content/docs/learn/guides/mainnet-migration.md @@ -5,7 +5,7 @@ description: Detailed instructions for migrating your ERC20/BEP20 DUSK tokens to This guide explains how to migrate **ERC20/BEP20 DUSK** (Ethereum/BSC) to **native DUSK** on Dusk mainnet. The migration flow is handled through the [Web Wallet](https://apps.dusk.network/wallet/) and uses WalletConnect to connect your EVM wallet. -The migration process locks your ERC20/BEP20 DUSK in a smart contract on Ethereum or Binance Smart Chain. Once locked, an event is emitted and native DUSK is issued to your Dusk wallet. The entire process typically takes around 15 minutes. +The migration process locks your ERC20/BEP20 DUSK in a smart contract on Ethereum or Binance Smart Chain. Once locked, an event is emitted and native DUSK is issued to your Dusk wallet. The entire process typically takes around one hour. :::note Want to bridge **native DUSK to BEP20 DUSK** on BSC instead? See: [Native DUSK to BEP20 Bridge](/learn/guides/bep20-bridge). @@ -20,12 +20,12 @@ Want to bridge **native DUSK to BEP20 DUSK** on BSC instead? See: [Native DUSK t - A Dusk wallet (in the Web Wallet) where you want to receive native DUSK. - An EVM wallet holding ERC20/BEP20 DUSK that supports WalletConnect. -- ETH or BNB to pay the Ethereum/BSC transaction fee for the lock transaction. +- Enough ETH or BNB to pay for two Ethereum/BSC transactions. ## Expected time and fees -- **Time**: typically ~15 minutes once your Ethereum/BSC transaction is confirmed. -- **Fees**: you pay the normal Ethereum/BSC network fee to submit the lock transaction. +- **Time**: typically around one hour once the **Execute migration** transaction is confirmed. +- **Fees**: you normally pay an Ethereum/BSC network fee once to approve the migration and again to start it. ## Steps @@ -33,19 +33,27 @@ Want to bridge **native DUSK to BEP20 DUSK** on BSC instead? See: [Native DUSK t 2. Import an existing wallet or create a new one. 3. You will be asked to initiate the migration. Review and confirm the process. 4. Connect your Web3 wallet via WalletConnect. -5. Confirm the transaction in your Web3 wallet. A migration function will be triggered with your Dusk mainnet wallet address as the target address. +5. Select **Approve migration** and confirm the request in your Web3 wallet. This gives the migration permission to use the selected amount of DUSK; it does not move the tokens. +6. Wait for the Web Wallet to report that approval succeeded. +7. Select **Execute migration** and confirm the second request in your Web3 wallet. This moves the selected DUSK into the migration process and starts the transfer to your Dusk wallet. -Wait for the issuance of your native DUSK tokens. This process can take up to 15 minutes for security reasons. +If your Web3 wallet has already granted enough permission for the selected amount, the Web Wallet may proceed directly to **Execute migration**. + +Wait for the issuance of your native DUSK tokens. This process typically takes around one hour. ## FAQ **How long does the migration process take?** -The migration process typically completes within 15 minutes from the time you initiate the transaction. It will depend on network activity on both chains. +The migration process typically completes around one hour after the **Execute migration** transaction is confirmed. Network activity on both chains can affect the timing. **How can I track my migration transaction?** -You can track the migration transaction in your Web3 wallet on Ethereum or Binance Smart Chain. Once the migration is complete, the original Ethereum/Binance Smart Chain transaction hash will be included in the memo field of the Dusk transaction for reference. +Track the second, **Execute migration** transaction in your Web3 wallet on Ethereum or Binance Smart Chain. Once the migration is complete, that transaction hash will be included in the memo field of the Dusk transaction for reference. + +**Why does my wallet ask me to confirm twice?** + +The first confirmation gives the migration permission to use the selected DUSK. The second confirmation starts the migration. Approving alone does not move any tokens. **Is there a minimum amount of DUSK I can migrate?** @@ -61,6 +69,7 @@ This rounding behavior ensures that only full LUX amounts are migrated to native ## Troubleshooting - **My migration transaction is pending or failed**: check it in your EVM wallet and ensure you have enough ETH/BNB for gas. -- **I don’t see native DUSK after ~15 minutes**: confirm the Ethereum/BSC lock transaction is successful and give it a bit more time during congestion. +- **Approval succeeded but the migration did not start**: return to the Web Wallet and select **Execute migration**. Approval alone does not move any DUSK. +- **I don’t see native DUSK after around one hour**: confirm the Ethereum/BSC lock transaction is successful and give it more time during congestion. - **My migrated amount is smaller than expected**: amounts are rounded down to full `LUX` (see above). - **I’m trying to migrate from an exchange**: exchanges usually can’t connect via WalletConnect. Withdraw your DUSK to a self-custody wallet first. diff --git a/src/content/docs/learn/overview.mdx b/src/content/docs/learn/overview.mdx index 4f558bd6..283d7973 100644 --- a/src/content/docs/learn/overview.mdx +++ b/src/content/docs/learn/overview.mdx @@ -71,7 +71,7 @@ Dusk separates settlement from execution: Assets can move between layers so you can use the right environment for each job. -See: [Core Components](/learn/core-components) and [DuskEVM Developer Docs](/developer/smart-contracts-dusk-evm/deploy-on-evm). +See: [Core Components](/learn/core-components) and the [DuskEVM quickstart](/developer/duskevm/quickstart/). ## What can you build on Dusk? @@ -102,7 +102,7 @@ Here’s how the main components fit together: | Component | Role in the system | Learn more | | ---------- | ------------------------------------------------------------------ | ------------------------------------------- | | **DuskDS** | Dusk L1: settlement, consensus, data availability, and native transaction models | [Core Components](/learn/core-components) | -| **DuskEVM**| EVM execution environment where DUSK is the gas token | [Deploy on DuskEVM](/developer/smart-contracts-dusk-evm/deploy-on-evm) | +| **DuskEVM**| EVM execution environment where DUSK is the gas token | [Build on DuskEVM](/developer/duskevm/quickstart/) | | **Rusk** | Reference node implementation that runs Succinct Attestation | [Run a node](/operator/overview) | | **Citadel**| Identity and access primitives for selective disclosure and regulated flows | [Core Components](/learn/core-components#citadel) | diff --git a/src/content/docs/operator/guides/node-wallet-setup.md b/src/content/docs/operator/guides/node-wallet-setup.md index fe4c3470..e99e6a08 100644 --- a/src/content/docs/operator/guides/node-wallet-setup.md +++ b/src/content/docs/operator/guides/node-wallet-setup.md @@ -79,7 +79,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/networks#how-to-get-testnet-tokens). The minimum stake is 1000 nDUSK. +You can request 5,000 testnet DUSK from our [Discord faucet](/operator/networks#how-to-get-testnet-tokens). The minimum testnet stake is 1,000 DUSK. ## Stake your DUSK diff --git a/src/content/docs/operator/guides/upgrade-node.mdx b/src/content/docs/operator/guides/upgrade-node.mdx index 168cbd21..ecdc9017 100644 --- a/src/content/docs/operator/guides/upgrade-node.mdx +++ b/src/content/docs/operator/guides/upgrade-node.mdx @@ -103,9 +103,9 @@ 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. -5. If you do not have testnet DUSK (nDUSK), request it from the [faucet](/operator/networks#how-to-get-testnet-tokens). +5. If you do not have testnet DUSK, request it from the [faucet](/operator/networks#how-to-get-testnet-tokens). -6. Stake your nDUSK: +6. Stake your testnet DUSK: ```sh rusk-wallet stake --amt 1000 # Or however much you want to stake ``` diff --git a/src/content/docs/operator/networks.md b/src/content/docs/operator/networks.md index d34386b6..2a57b260 100644 --- a/src/content/docs/operator/networks.md +++ b/src/content/docs/operator/networks.md @@ -45,7 +45,7 @@ Some of the functions for the Nocturne Testnet are: ### How to get testnet tokens -The Dusk Nocturne testnet uses a Discord bot to distribute Nocturne tokens (nDUSK). +The Dusk Nocturne testnet uses a Discord bot to distribute testnet DUSK. Testnet DUSK has no real-world value. In order to access it, follow these steps: diff --git a/src/sidebars/siteSidebar.js b/src/sidebars/siteSidebar.js index fd2570a1..59cefc62 100644 --- a/src/sidebars/siteSidebar.js +++ b/src/sidebars/siteSidebar.js @@ -11,6 +11,7 @@ const siteSidebar = [ { label: "Market Infrastructure", link: "/learn/market-infrastructure" }, { label: "Dusk Trade", link: "/learn/dusk-trade" }, { label: "Core Components", link: "/learn/core-components" }, + { label: "DuskEVM", link: "/learn/dusk-evm" }, { label: "Core Values", link: "/learn/core-values" }, { label: "Native Issuance", link: "/learn/tokenization-comparison" }, { label: "Ecosystem & Partners", link: "/learn/ecosystem" }, @@ -31,7 +32,7 @@ const siteSidebar = [ label: "Guides", items: [ { label: "How to Stake", link: "/learn/guides/staking-basics" }, - { label: "DuskEVM Bridge", link: "/learn/guides/duskevm-bridge" }, + { label: "Bridge DUSK", link: "/learn/guides/duskevm-bridge" }, { label: "Mainnet DUSK Migration", link: "/learn/guides/mainnet-migration" }, { label: "BEP20 Bridge", link: "/learn/guides/bep20-bridge" }, { label: "Verify Team Account", link: "/learn/verify-team-account" }, @@ -45,7 +46,6 @@ const siteSidebar = [ { label: "Transaction Models", link: "/learn/deep-dive/duskds-tx-models" }, { label: "Assets & Regulations", link: "/learn/deep-dive/assets-and-regulations" }, { label: "DuskVM", link: "/learn/deep-dive/dusk-vm" }, - { label: "DuskEVM", link: "/learn/deep-dive/dusk-evm" }, { label: "Additional Resources", link: "/learn/deep-dive/additional-resources" }, ], }, @@ -59,7 +59,8 @@ const siteSidebar = [ { label: "Build on Dusk", items: [ - { label: "Deploy on DuskEVM", link: "/developer/smart-contracts-dusk-evm/deploy-on-evm" }, + { label: "DuskEVM Quickstart", link: "/developer/duskevm/quickstart" }, + { label: "DuskEVM Reference", link: "/developer/duskevm/reference" }, { label: "Smart Contracts on DuskDS", link: "/developer/smart-contracts-duskds" }, { label: "Stake Abstraction", link: "/learn/hyperstaking" }, { label: "Digital Identity Protocol", link: "/developer/digital-identity/protocol" },