Merge pull request #121 from dusk-network/docs/rusk-alignment

Align docs with rusk

Author: HDauven

src/content/docs/developer/integrations/exchanges.md

@@ -8,11 +8,15 @@ description: "Practical notes for listing DUSK: connectivity, deposits/withdrawa
 - Decide how you'll access the network:
   - Run your own node (recommended for production).
   - Use public endpoints (good for prototyping).
-  - Run (or use) an archive node if you need address-based history queries.
+  - Run (or use) an archive node if you need address-based history queries such as `fullMoonlightHistory` or `moonlightHistory`.
 - Support Moonlight (public) deposits and withdrawals.
 - Handle finality and reverts: treat funds as final once the containing block is `finalized`, and re-process if a block is reverted.
 - Use the memo field if you need per-user tagging.
 
+:::tip[Use W3sper for Transaction Submission]
+For transaction construction, signing, and submission, prefer the [W3sper SDK](/developer/integrations/w3sper). Use raw HTTP endpoints only if you are building lower-level infrastructure around RUES.
+:::
+
 ## Network Access
 
 Base URLs:
@@ -30,7 +34,7 @@ For the full HTTP/WS API and event subscription model (RUES), see [/developer/in
 
 Two common approaches:
 
-- **Archive GraphQL (simplest):** poll `fullMoonlightHistory` or `moonlightHistory`. See [/developer/integrations/historical_events](/developer/integrations/historical_events).
+- **Archive GraphQL (simplest):** poll `fullMoonlightHistory` or `moonlightHistory` on an archive-enabled node. See [/developer/integrations/historical_events](/developer/integrations/historical_events).
 - **Real-time (RUES):** subscribe to blocks/transactions and correlate with GraphQL `tx(hash: ...)` lookups.
 
 ## Submitting Withdrawals

src/content/docs/developer/integrations/historical_events.md

@@ -5,7 +5,9 @@ description: Documentation on the access to blockchain transaction history for p
 
 ## Overview
 
-The GraphQL API provides access to finalized historical blockchain transaction-events, involving public (Moonlight) `DUSK` value transfers. It includes two primary endpoints:
+These queries are **archive-only**. You need an archive-enabled node, or a public archive endpoint, to use them. On a non-archive node they are unavailable.
+
+The archive GraphQL API provides access to finalized historical blockchain transaction-events involving public (Moonlight) `DUSK` value transfers. It includes two primary endpoints:
 
 1. `moonlightHistory`
 2. `fullMoonlightHistory`

src/content/docs/developer/integrations/http-api.md

@@ -3,8 +3,14 @@ title: HTTP API
 description: Query nodes, broadcast transactions, and subscribe to real-time events using RUES over HTTP and WebSocket.
 ---
 
+:::tip[Prefer W3sper First]
+For application integrations, prefer the [W3sper SDK](/developer/integrations/w3sper). It wraps transaction building, proving, submission, and common node interactions.
+:::
+
 The <a href="https://github.com/dusk-network/rusk/wiki/RUES-%28Rusk-Universal-Event-System%29" target="_blank"><strong>Rusk Universal Event System (RUES)</strong></a> is the public interface exposed by Dusk nodes.
 
+This page covers the common low-level HTTP and WebSocket surface. Treat it as an implementation guide, not as a frozen protocol spec.
+
 - Use **HTTP `POST`** for request/response calls (query node state, submit transactions, generate proofs, etc.).
 - Use **WebSocket + HTTP `GET`/`DELETE`** for real-time event subscriptions.
 
@@ -52,6 +58,10 @@ If the requested version is incompatible, the node rejects the request.
 **Method**: `POST`  
 **Body**: a GraphQL query string.
 
+:::note
+Archive-only GraphQL fields such as `moonlightHistory`, `fullMoonlightHistory`, and `finalizedEvents` require an archive-enabled node.
+:::
+
 ### Get the schema (SDL)
 
 Send an empty body to retrieve the schema:
@@ -257,5 +267,5 @@ Events are sent as WebSocket **binary messages**:
 2. JSON header bytes (includes `Content-Location`).
 3. Raw event data bytes (format depends on the event).
 
-If you need historical data (archive), use GraphQL queries such as `moonlightHistory` and `finalizedEvents`.
+If you need historical data, use an archive-enabled node and GraphQL queries such as `moonlightHistory`, `fullMoonlightHistory`, and `finalizedEvents`.
 See: [Retrieve historical events](/developer/integrations/historical_events).

src/content/docs/developer/integrations/w3sper.md

@@ -3,12 +3,12 @@ title: W3sper SDK
 description: JavaScript SDK for generating profiles, building transactions, and querying Dusk nodes.
 ---
 
-W3sper (`@dusk/w3sper`) is the JavaScript SDK used by Dusk apps and tooling to interact with nodes.
+W3sper (`@dusk/w3sper`) is the JavaScript SDK used by Dusk apps and tooling to interact with nodes. Prefer it over calling raw RUES endpoints directly from application code.
 
 ## Install
 
 ```sh
-npm install @dusk/w3sper
+deno add jsr:@dusk/w3sper
 ```
 
 ## Connect
@@ -75,15 +75,17 @@ console.log(tip.block.header);
 
 ## Offline Mode (Optional)
 
-When you call `Network.connect(...)`, W3sper loads the wallet-core WASM driver from the node (`/static/drivers/`).
-For offline usage, load the driver yourself:
+When you call `Network.connect(...)`, W3sper loads the matching `wallet-core` WASM driver from the node.
+For the current 1.6 line, that driver is served as `wallet-core-1.6.0.wasm`.
+
+For offline usage, download that same versioned driver and load it yourself:
 
 ```js
 import { ProfileGenerator, useAsProtocolDriver } from "@dusk/w3sper";
 
 async function getLocalWasmBuffer() {
   // Must return bytes (Uint8Array/ArrayBuffer). Adjust to your environment.
-  return Deno.readFile("./wallet-core.wasm");
+  return Deno.readFile("./wallet-core-1.6.0.wasm");
 }
 
 const seeder = () => crypto.getRandomValues(new Uint8Array(64));
@@ -97,8 +99,8 @@ await useAsProtocolDriver(await getLocalWasmBuffer()).then(async () => {
 
 WASM download URLs:
 
-- Mainnet: `https://nodes.dusk.network/static/drivers/wallet-core.wasm`
-- Testnet: `https://testnet.nodes.dusk.network/static/drivers/wallet-core.wasm`
+- Mainnet: `https://nodes.dusk.network/static/drivers/wallet-core-1.6.0.wasm`
+- Testnet: `https://testnet.nodes.dusk.network/static/drivers/wallet-core-1.6.0.wasm`
 
 ## Units
 

src/content/docs/learn/glossary.md

@@ -11,7 +11,7 @@ Accounts in Dusk manage transactions with different visibility levels. An accoun
 
 #### Archive Node
 
-An [archive node](/operator/archive-node) stores the full historical record of the Dusk blockchain and does not participate in consensus.
+An [archive node](/operator/archive-node) stores the full historical record of the Dusk blockchain and exposes archive-specific historical queries. Archive mode can also participate in consensus because it extends the regular node stack rather than replacing it.
 
 #### Citadel
 

src/content/docs/learn/hyperstaking.md

@@ -44,7 +44,7 @@ Stake abstraction requires contracts to interact with the genesis **Stake Contra
 - Transfer contract source:
   <a href="https://raw.githubusercontent.com/dusk-network/contracts/main/genesis/transfer/src/state.rs" target="_blank" rel="noreferrer">genesis/transfer</a>
 - Example implementation:
-  <a href="https://raw.githubusercontent.com/dusk-network/rusk/refs/heads/master/contracts/charlie/src/state.rs" target="_blank" rel="noreferrer">rusk/contracts/charlie</a>
+  <a href="https://raw.githubusercontent.com/dusk-network/rusk/refs/heads/master/contracts/tests/charlie/src/state.rs" target="_blank" rel="noreferrer">rusk/contracts/tests/charlie</a>
 
 ### Required Stake Contract calls
 

src/content/docs/learn/rusk-wallet.md

@@ -7,9 +7,18 @@ description: "The official CLI wallet for Dusk: scripting, staking, and operator
 
 If you prefer a UI for everyday transfers, use the [Web Wallet](/learn/web-wallet).
 
+Use these as the source of truth for your installed version:
+
+- The upstream CLI reference:
+  <a href="https://github.com/dusk-network/rusk/blob/master/rusk-wallet/src/bin/README.md" target="_blank" rel="noreferrer">rusk-wallet/src/bin/README.md</a>
+- The current releases:
+  <a href="https://github.com/dusk-network/rusk/releases?q=rusk+wallet&expanded=true" target="_blank" rel="noreferrer">Rusk releases</a>
+- Your local help output:
+  `rusk-wallet --help` and `rusk-wallet <command> --help`
+
 ## Install
 
-- Download a prebuilt binary from the <a href="https://github.com/dusk-network/rusk/releases?q=rusk+wallet&expanded=true" target="_blank" rel="noreferrer">Rusk releases page</a>.
+- Download a prebuilt binary from the releases page.
 - Or build from source from the <a href="https://github.com/dusk-network/rusk" target="_blank" rel="noreferrer">rusk repo</a>.
 
 ## Usage
@@ -33,61 +42,27 @@ rusk-wallet --help
 rusk-wallet <command> --help
 ```
 
-The full CLI command reference lives in the upstream README:
-<a href="https://github.com/dusk-network/rusk/blob/master/rusk-wallet/src/bin/README.md" target="_blank" rel="noreferrer">rusk-wallet/src/bin/README.md</a>.
-
-## Common tasks
-
-### Create or restore a wallet
-
-```bash
-rusk-wallet create
-```
-
-```bash
-rusk-wallet restore
-```
+## Non-interactive use (automation)
 
-### Check balance
+Most commands prompt for a wallet password when they need to decrypt secrets. For automation, you can provide it via `RUSK_WALLET_PWD`:
 
 ```bash
+export RUSK_WALLET_PWD=<your_password>
 rusk-wallet balance
 ```
 
-### Transfer funds
-
-Use the built-in help for the exact flags:
+For exporting provisioner keys in headless environments:
 
 ```bash
-rusk-wallet transfer --help
+export RUSK_WALLET_EXPORT_PWD=<export_password>
 ```
 
-### Stake (owner key optional)
-
-A Dusk stake has two roles:
-
-- **Consensus key**: used to participate in consensus.
-- **Owner key**: the address that can `unstake` and `withdraw`.
-
-If you don't specify `--owner`, the consensus key is also the owner.
-
-```bash
-# Stake with the default owner (consensus key)
-rusk-wallet stake --amt 1000
-
-# Stake with a separate owner address
-rusk-wallet stake --amt 1000 --owner <OWNER_ADDRESS>
-```
-
-For the node-operator flow (exporting consensus keys, staking, and monitoring with `stake-info`), follow: [Wallet setup](/operator/guides/node-wallet-setup).
-
-## Non-interactive use (automation)
+Only do this in controlled environments, and be careful not to leak passwords via shell history, logs, or CI output.
 
-Most commands prompt for a wallet password when they need to decrypt secrets. For automation, you can provide it via `RUSK_WALLET_PWD`:
+## Operator workflows
 
-```bash
-export RUSK_WALLET_PWD=<your_password>
-rusk-wallet balance
-```
+If you are using the wallet for provisioner or archive-node operations, see:
 
-Only do this in controlled environments, and be careful not to leak passwords via shell history, logs, or CI output.
+- [Node wallet setup](/operator/guides/node-wallet-setup)
+- [Provisioner node](/operator/provisioner)
+- [Archive node](/operator/archive-node)

src/content/docs/operator/archive-node.md

@@ -3,13 +3,14 @@ title: Run an archive node
 description: Learn about Dusk archive nodes that store and give access to Dusk’s historical data.
 ---
 
-Archive nodes extend the functionality of [Provisioners](/operator/provisioner) by also preserving a complete historical record of the Dusk blockchain. While Provisioners are focused solely on the current state, archive nodes provide essential long-term data access that supports applications, users, researchers, and auditors who need comprehensive historical information.
+Archive nodes extend the functionality of [Provisioners](/operator/provisioner) by also preserving a complete historical record of the Dusk blockchain. While provisioners focus on the current state and consensus duties, archive mode adds long-term historical data access for applications, users, researchers, and auditors.
 
-Archive nodes play a unique role in the Dusk Network by focusing on data storage and accessibility, rather than participating in consensus. This means they are not required to stake DUSK, as they serve an entirely supportive function for dApps and services that rely on historical records.
+Archive nodes are commonly run as data-serving infrastructure and do not need to stake DUSK. However, archive mode is built on top of the regular node stack, so an archive node can also be configured to participate in consensus if you choose to stake and run it that way.
 
 In short, archive nodes:
 - Provide additional historical data (such as events emitted by contracts) that is not stored by a Provisioner node
-- Can participate in consensus, by staking DUSK. However, they are not required to.
+- Expose archive-only GraphQL queries such as `moonlightHistory`, `fullMoonlightHistory`, and `finalizedEvents`
+- Can also participate in consensus by staking DUSK, though that is optional
 
 :::tip[Run an Archive node]
 If you want to quickly launch & run an archive node, you can use the <a href="https://github.com/dusk-network/node-installer" target="_blank">node installer</a> by following [the archive guide](/operator/archive-node).
@@ -83,7 +84,9 @@ You can check which GraphQL queries are available by retrieving the schema (SDL)
 curl -s -X POST "http://<your-node-host>:8080/on/graphql/query"
 ```
 
-This should now return a different list than a normal node returns. An example endpoint that is now available is the **checkBlock** endpoint, which returns true or false whether a block height matches a specific block hash, which can also be queried only for finalized blocks.
+This should now return a different schema than a normal node returns. Archive-enabled nodes expose additional historical queries such as `moonlightHistory`, `fullMoonlightHistory`, and `finalizedEvents`.
+
+A regular node also exposes `checkBlock`, but the `onlyFinalized: true` behavior below is archive-only.
 
 In order to test this endpoint, you can run the following command.
 

src/content/docs/operator/guides/manual-resync.md

@@ -65,7 +65,7 @@ ruskquery block-height
 Once your node is close to the current block height, you can restake your DUSK tokens:
 
 ```sh
-rusk-wallet stake <amount>
+rusk-wallet stake --amt <amount>
 ```
 Replace `<amount>` with the number of DUSK tokens you wish to stake.
 

src/content/docs/operator/troubleshooting.md

@@ -31,10 +31,12 @@ Answer with a capital **Y**, otherwise the operation will abort.
 Run the `ruskreset` command to fix this.
 
 #### "stake" command not recognized
-If staking via Moonlight, you can launch:
+Use the current CLI help output as the source of truth for your installed wallet version. The normal staking flow uses `stake`, for example:
 
 ```bash
-rusk-wallet moonlight-stake --amt 3000
+rusk-wallet --help
+rusk-wallet stake --help
+rusk-wallet stake --amt 3000
 ```
 
 #### Serialization error