Restructure DuskVM contract documentation

astro.config.js

@@ -34,6 +34,11 @@ export default defineConfig({
 		'/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',
+		'/developer/smart-contracts-duskds': '/developer/duskvm/overview',
+		'/developer/duskds': '/developer/duskvm/overview',
+		'/developer/duskds/overview': '/developer/duskvm/overview',
+		'/developer/duskds/quickstart': '/developer/duskvm/quickstart',
+		'/developer/duskds/reference': '/developer/duskvm/reference',
 	},
 	integrations: [
 		starlight({

public/llms-full.txt

@@ -8,12 +8,13 @@ Dusk is infrastructure for regulated digital assets and general finance. It is d
 
 Dusk should be understood as a stack:
 
-- DuskDS: the Dusk L1 for consensus, settlement, data availability, native transaction models, and native execution.
-- DuskEVM: an OP Stack-based EVM execution environment using DUSK as gas and DuskDS for settlement/data availability.
-- DuskVM: the WASM execution environment for native Dusk smart contracts.
-- Rusk: the Rust node implementation that runs DuskDS.
+- Dusk L1: the complete base network, combining DuskDS settlement and data availability with DuskVM execution.
+- DuskDS: the consensus, settlement, and data-availability foundation of the Dusk L1, including its Moonlight and Phoenix transaction models.
+- DuskVM: the Rust/WASM smart-contract execution environment that runs directly on the Dusk L1.
+- DuskEVM: an OP Stack-based EVM execution environment using DUSK as gas and DuskDS for settlement and data availability.
+- Rusk: the Rust node implementation for the Dusk L1; it runs DuskDS consensus and DuskVM execution.
 - Citadel: identity and access primitives for selective disclosure and regulated workflows.
-- Dusk Connect: wallet discovery and account connection for Dusk applications.
+- Dusk Connect: wallet-extension discovery, profile access, and user-approved transactions for browser dApps.
 - Dusk Trade: application-layer market infrastructure for tokenized financial assets.
 
 ## Key Concepts
@@ -62,16 +63,18 @@ Relevant docs:
 
 Dusk has two main developer paths:
 
-- DuskEVM: Solidity, EVM tooling, EVM wallets, Ethereum-compatible infrastructure.
-- Native Dusk: general-purpose Rust/WASM contracts through DuskVM for protocol-level assets, native transaction models, custom execution, market logic, privacy, or zero-knowledge capabilities close to the settlement layer.
+- DuskVM: Rust/WASM contracts executed directly on the Dusk L1.
+- DuskEVM: Solidity, EVM tooling, EVM wallets, and Ethereum-compatible infrastructure settled through DuskDS.
 
 Relevant docs:
 
 - https://docs.dusk.network/developer/overview/
-- https://docs.dusk.network/learn/deep-dive/dusk-evm/
+- https://docs.dusk.network/learn/dusk-evm/
 - https://docs.dusk.network/learn/deep-dive/dusk-vm/
-- https://docs.dusk.network/developer/smart-contracts-dusk-evm/deploy-on-evm/
-- https://docs.dusk.network/developer/smart-contracts-duskds/
+- https://docs.dusk.network/developer/duskevm/quickstart/
+- https://docs.dusk.network/developer/duskvm/overview/
+- https://docs.dusk.network/developer/duskvm/quickstart/
+- https://docs.dusk.network/developer/duskvm/reference/
 
 ## Important Pages
 
@@ -90,8 +93,10 @@ Relevant docs:
 ### Developer
 
 - Developer Overview: https://docs.dusk.network/developer/overview/
-- Deploy on DuskEVM: https://docs.dusk.network/developer/smart-contracts-dusk-evm/deploy-on-evm/
-- Smart Contracts on DuskDS: https://docs.dusk.network/developer/smart-contracts-duskds/
+- DuskEVM Quickstart: https://docs.dusk.network/developer/duskevm/quickstart/
+- DuskVM Overview: https://docs.dusk.network/developer/duskvm/overview/
+- DuskVM Quickstart: https://docs.dusk.network/developer/duskvm/quickstart/
+- DuskVM Contract Reference: https://docs.dusk.network/developer/duskvm/reference/
 - Dusk Connect: https://docs.dusk.network/developer/integrations/dusk-connect/
 - Dusk Wallet Extension: https://docs.dusk.network/developer/integrations/wallet-extension/
 - Transaction Lifecycle: https://docs.dusk.network/developer/integrations/tx-lifecycle/
@@ -124,10 +129,10 @@ Relevant docs:
 
 Use:
 
-- Dusk for the network/protocol/stack in general contexts.
-- DuskDS for the Dusk L1, settlement, consensus, data availability, and native transaction models.
-- DuskEVM for the EVM execution layer.
-- DuskVM for native WASM smart contract execution.
+- Dusk for the company, product suite, and network in general contexts; use Dusk network or Dusk L1 when the technical meaning could be ambiguous.
+- DuskDS for the settlement and data-availability foundation, not as a synonym for the complete Dusk L1.
+- DuskVM for Rust/WASM smart-contract execution directly on the Dusk L1.
+- DuskEVM for the EVM execution layer settled through DuskDS.
 - Moonlight for public account flows.
 - Phoenix for shielded transfer flows.
 - Privacy with selective disclosure for regulated privacy patterns.

public/llms.txt

@@ -13,10 +13,12 @@
 
 ## Developer Docs
 
-- [Build on Dusk](https://docs.dusk.network/developer/overview/): choose between DuskEVM and native Dusk development.
-- [Deploy on DuskEVM](https://docs.dusk.network/developer/smart-contracts-dusk-evm/deploy-on-evm/): deploy Solidity contracts on DuskEVM.
-- [Smart Contracts on DuskDS](https://docs.dusk.network/developer/smart-contracts-duskds/): write Rust/WASM contracts for native Dusk execution.
-- [Dusk Connect](https://docs.dusk.network/developer/integrations/dusk-connect/): integrate wallet discovery and account connection.
+- [Build on Dusk](https://docs.dusk.network/developer/overview/): choose between DuskVM and DuskEVM development.
+- [DuskEVM Quickstart](https://docs.dusk.network/developer/duskevm/quickstart/): deploy Solidity contracts on DuskEVM.
+- [DuskVM Overview](https://docs.dusk.network/developer/duskvm/overview/): understand Rust/WASM contracts that execute directly on the Dusk L1.
+- [DuskVM Quickstart](https://docs.dusk.network/developer/duskvm/quickstart/): create, test, build, and deploy a DuskVM contract.
+- [DuskVM Contract Reference](https://docs.dusk.network/developer/duskvm/reference/): understand the DuskVM contract, ABI, state, event, and deployment model.
+- [Dusk Connect](https://docs.dusk.network/developer/integrations/dusk-connect/): discover wallet extensions, request profile access, and submit user-approved transactions from browser dApps.
 - [Dusk Wallet Extension](https://docs.dusk.network/developer/integrations/wallet-extension/): integrate with the first-party browser wallet provider.
 - [Transaction Lifecycle](https://docs.dusk.network/developer/integrations/tx-lifecycle/): understand transaction flow.
 - [HTTP API](https://docs.dusk.network/developer/integrations/http-api/): integrate with Dusk APIs.
@@ -25,8 +27,8 @@
 ## Learn
 
 - [Transaction Models](https://docs.dusk.network/learn/deep-dive/duskds-tx-models/): Moonlight public accounts and Phoenix shielded transfers.
-- [DuskEVM](https://docs.dusk.network/learn/deep-dive/dusk-evm/): OP Stack-based EVM execution on Dusk.
-- [DuskVM](https://docs.dusk.network/learn/deep-dive/dusk-vm/): WASM execution for native Dusk contracts.
+- [DuskEVM](https://docs.dusk.network/learn/dusk-evm/): OP Stack-based EVM execution on Dusk.
+- [DuskVM](https://docs.dusk.network/learn/deep-dive/dusk-vm/): Rust/WASM smart-contract execution directly on the Dusk L1.
 - [Assets & Regulations](https://docs.dusk.network/learn/deep-dive/assets-and-regulations/): regulated asset workflow concepts.
 - [Cryptography](https://docs.dusk.network/learn/cryptography/): zero-knowledge proofs and cryptographic building blocks.
 

src/components/ResourceLinksGrid.astro

@@ -19,8 +19,8 @@ import { LinkCard, CardGrid } from "@astrojs/starlight/components";
         description="Learn how DUSK is used for fees and staking, and how emissions and rewards work."
     />
     <LinkCard
-        title="Smart Contract Example"
-        href="/developer/smart-contracts-duskds/"
-        description="Start with the DuskDS smart contract quickstart (includes the my-first-contract template)."
+        title="DuskVM Contract Example"
+        href="/developer/duskvm/quickstart/"
+        description="Create, test, build, and deploy a Rust/WASM contract with Forge."
     />
 </CardGrid>

src/content/docs/developer/duskevm/reference.md

@@ -39,8 +39,8 @@ Use `eth_estimateGas` to estimate the execution limit and EIP-1559 fee fields wh
 
 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.
+- **Deposits** are credited on DuskEVM after the Dusk L1 deposit is processed.
+- **Withdrawals** require proof, network finality checks, and a separate Dusk L1 finalization transaction.
 
 Use the bridge, wallet, or protocol contract status instead of calculating withdrawal readiness from time alone.
 
@@ -52,7 +52,7 @@ Most Solidity contracts require no Dusk-specific changes. Account for these OP S
 |---|---|
 | `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. |
+| `tx.origin` in deposits | Contract-originated Dusk L1 to DuskEVM deposits use OP address aliasing. Use cross-domain messaging when the original sender identity matters. |
 
 ## Contract verification
 

src/content/docs/developer/duskvm/overview.md

@@ -0,0 +1,36 @@
+---
+title: DuskVM smart contracts
+description: Build Rust and WebAssembly smart contracts that execute directly on the Dusk L1.
+---
+
+DuskVM contracts are written in Rust, compiled to WebAssembly (WASM), and executed directly on the Dusk L1. They use the Dusk contract ABI and can integrate with L1 protocol contracts and transaction models.
+
+This path gives contracts direct access to Dusk's L1 execution model, but uses Dusk-specific tooling rather than the Ethereum toolchain.
+
+## Choose an execution environment
+
+| Choose | When you need |
+|---|---|
+| **DuskVM** | Rust/WASM, Dusk L1 contracts and primitives, or logic that should execute directly on the L1 |
+| **[DuskEVM](/developer/duskevm/quickstart/)** | Solidity or Vyper, EVM wallets, and Ethereum-compatible libraries and tooling |
+
+Both environments are general-purpose. DuskVM executes contracts directly on the Dusk L1; DuskEVM provides EVM-compatible execution with settlement and data availability through DuskDS.
+
+## Toolchain
+
+| Component | Role |
+|---|---|
+| [Forge](https://github.com/dusk-network/forge) | Scaffolds contracts and generates ABI exports, schemas, and data drivers from annotated Rust |
+| [DuskVM](/learn/deep-dive/dusk-vm/) | Executes contract WASM and persists contract state |
+| [Rusk Wallet](/learn/rusk-wallet/) | Signs and submits deployment and contract-call transactions |
+| [Dusk Connect](/developer/integrations/dusk-connect/) | Connects browser dApps to compatible Dusk wallet extensions for account access and transaction approval |
+| [W3sper](/developer/integrations/w3sper/) | Connects JavaScript applications to Dusk nodes and contract data drivers |
+
+A typical workflow is:
+
+1. Scaffold a contract with Forge.
+2. Implement and test it locally against DuskVM.
+3. Build and verify the contract and data-driver WASM artifacts.
+4. Deploy the contract, then connect applications through Dusk Connect, W3sper, or the HTTP API.
+
+Start with the [DuskVM quickstart](/developer/duskvm/quickstart/). Use the [contract reference](/developer/duskvm/reference/) when you need the ABI, state, serialization, event, or deployment details.

src/content/docs/developer/duskvm/quickstart.md

@@ -0,0 +1,117 @@
+---
+title: DuskVM quickstart
+description: Create, test, build, and deploy a Rust/WASM contract with Forge.
+---
+
+This quickstart creates a counter contract with Forge 0.3, tests its compiled WASM in DuskVM, and builds the artifacts needed for deployment and application integration.
+
+## Prerequisites
+
+Install [Rust through rustup](https://www.rust-lang.org/tools/install), Git, and a C build toolchain (`build-essential` on Debian or Ubuntu, or Xcode Command Line Tools on macOS). Add the Rust component and compilation target required by Forge, then install the CLI from its tagged release:
+
+```bash
+rustup toolchain install stable \
+  --component rust-src \
+  --target wasm32-unknown-unknown
+
+cargo install --git https://github.com/dusk-network/forge \
+  --tag v0.3.0 dusk-forge-cli
+```
+
+The generated project selects that stable Rust toolchain and target through `rust-toolchain.toml`.
+
+## 1. Create the contract
+
+```bash
+dusk-forge new dusk-counter
+cd dusk-counter
+dusk-forge check
+```
+
+The project contains the contract in `src/lib.rs` and DuskVM integration tests in `tests/contract.rs`. Its `rust-toolchain.toml`, Cargo features, release overflow checks, and WASM target are ready for DuskVM development.
+
+The generated counter demonstrates the core model:
+
+- one Rust struct holds the contract state;
+- `pub const fn new() -> Self` creates its initial state;
+- public methods become contract entrypoints;
+- methods taking `&mut self` can update persisted state.
+
+## 2. Test in DuskVM
+
+```bash
+dusk-forge test
+```
+
+Forge first builds the contract WASM. The generated integration tests deploy that artifact into an isolated DuskVM session and exercise successful state changes and boundary behavior. A node, wallet, and DUSK are not required for these tests.
+
+## 3. Build and inspect
+
+```bash
+dusk-forge build
+dusk-forge schema --pretty
+dusk-forge verify
+```
+
+The build produces two WASM files from the same Rust source:
+
+| Artifact | Path |
+|---|---|
+| On-chain contract | `target/contract/wasm32-unknown-unknown/release/dusk_counter.wasm` |
+| Off-chain data driver | `target/data-driver/wasm32-unknown-unknown/release/dusk_counter.wasm` |
+
+`schema` lists the exported functions and registered events. `verify` checks both WASM artifacts and prints the contract hash.
+
+## 4. Encode call arguments
+
+Contract inputs use `rkyv`, not JSON or Solidity ABI encoding. Forge uses the data driver to encode readable input:
+
+```bash
+dusk-forge call set_count --input '42'
+```
+
+For the generated counter this returns:
+
+```text
+0x2a00000000000000
+```
+
+Keep the `0x` prefix when an SDK expects prefixed hex. Remove it for `rusk-wallet --fn-args`.
+
+## 5. Deploy on testnet
+
+Install and configure [Rusk Wallet](/learn/rusk-wallet/) and make sure a public account has enough testnet DUSK for deployment. [Request funds from the testnet faucet](/operator/networks/#how-to-get-testnet-tokens) if needed. The commands below target testnet explicitly and use the wallet's first address by default; add `--address <ADDRESS>` to use another funded address. Testnet DUSK has no monetary value.
+
+Deploy the on-chain artifact with a nonce you have not used for the same contract and account:
+
+```bash
+rusk-wallet --network testnet contract-deploy \
+  --code target/contract/wasm32-unknown-unknown/release/dusk_counter.wasm \
+  --deploy-nonce <UNIQUE_NONCE>
+```
+
+The wallet prints the contract ID and waits for the deployment transaction to be included. Keep the contract ID for later calls.
+
+Call an entrypoint with no arguments by passing an empty hex value:
+
+```bash
+rusk-wallet --network testnet contract-call \
+  --contract-id <CONTRACT_ID> \
+  --fn-name increment \
+  --fn-args ''
+```
+
+For a call with input, encode it with Forge and strip the prefix expected by Forge's output:
+
+```bash
+ARGS=$(dusk-forge call set_count --input '42')
+
+rusk-wallet --network testnet contract-call \
+  --contract-id <CONTRACT_ID> \
+  --fn-name set_count \
+  --fn-args "${ARGS#0x}"
+```
+
+`contract-call` submits a transaction and waits for inclusion. In a browser dApp, use [Dusk Connect](/developer/integrations/dusk-connect/) to discover wallet extensions, request account access, and ask the selected wallet to approve transactions. Use [W3sper](/developer/integrations/w3sper/) or the [Rusk HTTP API](/developer/integrations/http-api/) for direct node queries and contract data-driver integration.
+
+Before building a production contract, read the [DuskVM contract reference](/developer/duskvm/reference/).