Restructure DuskEVM documentation

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({

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 <CONTRACT_ADDRESS> \
+  --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/).

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/)

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
 <CardGrid>
   <LinkCard
     title="Smart Contracts on DuskEVM"
-    href="/developer/smart-contracts-dusk-evm/deploy-on-evm"
+    href="/developer/duskevm/quickstart"
     description="Deploy Solidity or Vyper contracts on DuskEVM using familiar EVM tooling."
   />
   <LinkCard
@@ -55,7 +55,7 @@ You get:
 - Settlement and data availability from DuskDS
 - A route toward confidential flows through Hedger where your application needs privacy
 
-See: [Smart Contracts on DuskEVM](/developer/smart-contracts-dusk-evm/deploy-on-evm).
+See: [DuskEVM quickstart](/developer/duskevm/quickstart/).
 
 ## When to use native Dusk contracts
 
@@ -86,4 +86,4 @@ You can explore existing contracts and examples in the Dusk repos:
 
 - 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)
+- DuskEVM examples in the [DuskEVM quickstart](/developer/duskevm/quickstart/)

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.
 

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/), <a href="https://github.com/dusk-network/rusk/" target="_blank" rel="noreferrer">GitHub</a> |
 | **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