add mdBook for m5

.github/workflows/static.yml

@@ -5,7 +5,7 @@ on:
   push:
     branches:
       - master
-      - add-docs-for-m5 # temporary — remove after verification
+      - add-docs-for-m5
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
@@ -34,18 +34,30 @@ jobs:
         uses: actions/checkout@v4
       - name: Setup Pages
         uses: actions/configure-pages@v5
-      - name: Build docs
+      - name: Install mdBook
+        uses: peaceiris/actions-mdbook@v2
+        with:
+          mdbook-version: 'latest'
+      - name: Build API reference (cargo doc)
         run: |
           npm run rust:doc
+      - name: Build mdBook guide
+        run: |
+          mdbook build docs/guide
+      - name: Assemble site
+        run: |
+          mkdir -p _site
+          cp -r docs/guide/book/* _site/
+          cp -r docs/ _site/api/
+          rm -rf _site/api/guide
       - name: Link check
         uses: lycheeverse/lychee-action@v2
         with:
-          args: --no-progress --config .lychee.toml ./docs
+          args: --no-progress --config .lychee.toml ./_site
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          # Upload entire repository
-          path: "./docs"
+          path: "./_site"
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4

.gitignore

@@ -5,9 +5,12 @@ target
 */**/schemas
 */**/output
 rust/pkg
-docs
+docs/*
+!docs/guide/
+docs/guide/book/
 
 */**/.env
 
 publish
+_site
 .claude

.lychee.toml

@@ -15,9 +15,20 @@ exclude = [
     "whisky_csl/core/builder/fn\\.js_serialize_tx_body",
     "whisky_js/builder/trait\\.ITxBuilderCore",
     "whisky_js/core/builder/fn\\.js_serialize_tx_body",
+    # mdBook relative ../api/ links resolve correctly over HTTP but not in lychee local file mode
+    "api/whisky/index\\.html",
+    "api/whisky_common/index\\.html",
+    "api/whisky_pallas/index\\.html",
+    "api/whisky_csl/index\\.html",
+    "api/whisky_provider/index\\.html",
+    "api/whisky_wallet/index\\.html",
+    "api/whisky_macros/index\\.html",
 ]
 
-# Exclude generated static files from Rust docs
+# Exclude generated static files from Rust docs and mdBook theme
 exclude_path = [
-    "docs/static.files",
+    "_site/static.files",
+    "_site/api/static.files",
+    # mdBook 404 page has a root-relative "/" link that lychee can't resolve locally
+    "_site/404.html",
 ]

README.md

@@ -11,6 +11,8 @@
 [![Crates.io](https://img.shields.io/crates/v/whisky?style=for-the-badge)](https://crates.io/crates/whisky)
 [![NPM](https://img.shields.io/npm/v/%40sidan-lab%2Fwhisky-js-nodejs?style=for-the-badge)](https://www.npmjs.com/package/@sidan-lab/whisky-js-nodejs)
 
+**[Read the Guide](https://sidan-lab.github.io/whisky/)** | **[API Reference](https://sidan-lab.github.io/whisky/api/whisky/index.html)**
+
   <hr/>
 </div>
 
@@ -308,7 +310,7 @@ Make sure llvm is installed
 
 ## APIs
 
-Please refer to the [hosted documentation](https://sidan-lab.github.io/whisky/whisky/index.html) for the list of endpoints.
+Please refer to the [Guide](https://sidan-lab.github.io/whisky/) and [API Reference](https://sidan-lab.github.io/whisky/api/whisky/index.html) for full documentation.
 
 ![Alt](https://repobeats.axiom.co/api/embed/2e35716a9dd3250972c06ca2b4c7f1846ef7c51e.svg "Repobeats analytics image")
 

docs/guide/book.toml

@@ -0,0 +1,13 @@
+[book]
+authors = ["SIDAN Lab"]
+language = "en"
+src = "src"
+title = "Whisky - Cardano Rust SDK Guide"
+
+[build]
+build-dir = "book"
+
+[output.html]
+git-repository-url = "https://github.com/sidan-lab/whisky"
+edit-url-template = "https://github.com/sidan-lab/whisky/edit/master/docs/guide/src/{path}"
+no-section-label = false

docs/guide/src/SUMMARY.md

@@ -0,0 +1,26 @@
+# Summary
+
+[Introduction](./introduction.md)
+
+# Getting Started
+
+- [Installation](./getting-started/installation.md)
+- [Quick Start](./getting-started/quickstart.md)
+
+# Core Guides
+
+- [Transaction Builder](./guides/tx-builder.md)
+  - [Simple Transactions](./guides/tx-builder/simple.md)
+  - [Plutus Script Transactions](./guides/tx-builder/plutus.md)
+  - [Minting](./guides/tx-builder/minting.md)
+  - [Staking & Governance](./guides/tx-builder/staking.md)
+- [Transaction Parser](./guides/tx-parser.md)
+- [Dependency Injection](./guides/dependency-injection.md)
+  - [Serializer Backends](./guides/di/serializers.md)
+  - [Providers](./guides/di/providers.md)
+- [Migration: CSL to Pallas](./guides/migration-csl-to-pallas.md)
+
+# Reference
+
+- [Examples Server](./reference/examples-server.md)
+- [API Documentation](./reference/api-docs.md)

docs/guide/src/getting-started/installation.md

@@ -0,0 +1,60 @@
+# Installation
+
+## Rust Library
+
+Add whisky to your project:
+
+```sh
+cargo add whisky
+```
+
+Or add it directly to your `Cargo.toml`:
+
+```toml
+[dependencies]
+whisky = "1.0.28-beta.1"
+```
+
+### Feature Flags
+
+By default, all features are enabled (`full`). You can selectively enable only what you need:
+
+```toml
+# Full (default) — includes wallet + provider
+whisky = "1.0.28-beta.1"
+
+# Just common types (minimal, no serializer backends)
+whisky = { version = "1.0.28-beta.1", default-features = false }
+
+# Wallet only (signing + key management)
+whisky = { version = "1.0.28-beta.1", default-features = false, features = ["wallet"] }
+
+# Provider only (Blockfrost/Maestro integrations)
+whisky = { version = "1.0.28-beta.1", default-features = false, features = ["provider"] }
+```
+
+| Feature | Includes | Use Case |
+|---------|----------|----------|
+| `full` (default) | wallet + provider | Full DApp backend |
+| `wallet` | Signing, key encryption | Transaction signing only |
+| `provider` | Blockfrost, Maestro | Blockchain data fetching |
+
+## JS / TS WASM Library
+
+For JavaScript or TypeScript projects, whisky is available as a WASM package:
+
+```sh
+# For Node.js
+yarn add @sidan-lab/whisky-js-nodejs
+
+# For browser
+yarn add @sidan-lab/whisky-js-browser
+```
+
+## Prerequisites
+
+For building from source, make sure LLVM is installed on your system:
+
+- **macOS**: `brew install llvm`
+- **Ubuntu/Debian**: `apt install llvm-dev libclang-dev`
+- **Windows**: Install via [LLVM releases](https://releases.llvm.org/)

docs/guide/src/getting-started/quickstart.md

@@ -0,0 +1,86 @@
+# Quick Start
+
+This guide shows you how to build your first Cardano transaction with whisky.
+
+## Your First Transaction
+
+The simplest transaction sends lovelace from one address to another. Here's the complete example:
+
+```rust,ignore
+use whisky::*;
+
+pub fn send_lovelace(
+    recipient_address: &str,
+    my_address: &str,
+    inputs: &[UTxO],
+) -> Result<String, WError> {
+    let mut tx_builder = TxBuilder::new_core();
+    tx_builder
+        .tx_out(
+            recipient_address,
+            &[Asset::new_from_str("lovelace", "1000000")],
+        )
+        .change_address(my_address)
+        .select_utxos_from(inputs, 5000000)
+        .complete_sync(None)?;
+
+    Ok(tx_builder.tx_hex())
+}
+```
+
+Let's break this down:
+
+1. **`TxBuilder::new_core()`** — Creates a new transaction builder with the default Pallas serializer
+2. **`.tx_out(address, assets)`** — Adds an output sending 1 ADA (1,000,000 lovelace) to the recipient
+3. **`.change_address(address)`** — Sets where leftover funds go after paying fees
+4. **`.select_utxos_from(inputs, threshold)`** — Automatically selects UTxOs from the provided set to cover outputs + fees. The threshold (5,000,000 lovelace) is extra headroom for fees and min UTxO
+5. **`.complete_sync(None)`** — Balances the transaction, calculates fees, and serializes to CBOR
+6. **`.tx_hex()`** — Returns the unsigned transaction as a hex-encoded CBOR string
+
+## Sync vs Async
+
+Whisky offers both synchronous and asynchronous completion:
+
+```rust,ignore
+// Synchronous — no script evaluation, no provider calls
+tx_builder.complete_sync(None)?;
+
+// Asynchronous — evaluates Plutus scripts, can fetch data from providers
+tx_builder.complete(None).await?;
+```
+
+Use `complete_sync` for simple transactions without scripts. Use `complete` (async) when your transaction includes Plutus scripts that need execution unit evaluation.
+
+## Signing
+
+After building, sign the transaction with a private key:
+
+```rust,ignore
+let signed_tx = tx_builder
+    .signing_key("your_signing_key_hex")
+    .complete_sync(None)?
+    .complete_signing()?;
+```
+
+The `signed_tx` string is ready for submission to the Cardano network.
+
+## Running the Tests
+
+Whisky includes comprehensive integration tests you can run to see these patterns in action:
+
+```sh
+# Run all tests
+cargo test
+
+# Run Pallas integration tests specifically
+cargo test --package whisky --test pallas_integration_tests
+
+# Run a specific test with output
+cargo test --package whisky --test pallas_integration_tests test_simple_spend -- --nocapture
+```
+
+## Next Steps
+
+- [Transaction Builder](../guides/tx-builder.md) — Explore all transaction building patterns
+- [Transaction Parser](../guides/tx-parser.md) — Parse and edit existing transactions
+- [Dependency Injection](../guides/dependency-injection.md) — Customize serializers and providers

docs/guide/src/guides/dependency-injection.md

@@ -0,0 +1,64 @@
+# Dependency Injection
+
+Whisky uses a trait-based dependency injection pattern that lets you swap out core components: the serializer backend, blockchain data fetcher, script evaluator, and transaction submitter.
+
+## TxBuilderParam
+
+When creating a `TxBuilder`, you can inject dependencies via `TxBuilderParam`:
+
+```rust,ignore
+use whisky::*;
+use whisky_pallas::WhiskyPallas;
+
+let mut tx_builder = TxBuilder::new(TxBuilderParam {
+    serializer: Box::new(WhiskyPallas::new(None)),  // Required
+    evaluator: None,    // Optional — defaults to OfflineTxEvaluator
+    fetcher: None,      // Optional — for blockchain data
+    submitter: None,    // Optional — for tx submission
+    params: None,       // Optional — protocol parameters
+});
+```
+
+Or use the convenience constructor with all defaults:
+
+```rust,ignore
+let mut tx_builder = TxBuilder::new_core();
+// Equivalent to: WhiskyPallas serializer, offline evaluator, no fetcher/submitter
+```
+
+## The TxBuilder Struct
+
+```rust,ignore
+pub struct TxBuilder {
+    pub serializer: Box<dyn TxBuildable>,       // Serializes tx body to CBOR
+    pub fetcher: Option<Box<dyn Fetcher>>,      // Fetches blockchain data
+    pub evaluator: Option<Box<dyn Evaluator>>,  // Evaluates Plutus scripts
+    pub submitter: Option<Box<dyn Submitter>>,  // Submits transactions
+    pub protocol_params: Option<Protocol>,      // Network parameters
+    // ... internal state fields
+}
+```
+
+## Why Dependency Injection?
+
+This design enables:
+
+- **Swappable serializers**: Use Pallas (recommended) or CSL backend without changing transaction logic
+- **Testing**: Mock fetchers and evaluators in unit tests
+- **Custom providers**: Implement your own blockchain data source
+- **Offline mode**: Build transactions without any network dependency (the default)
+- **Full pipeline**: Wire up fetcher + evaluator + submitter for end-to-end transaction handling
+
+## Trait Overview
+
+| Trait | Purpose | Built-in Implementations |
+|-------|---------|------------------------|
+| `TxBuildable` | Serialize transaction body to CBOR | `WhiskyPallas`, `WhiskyCSL` |
+| `Fetcher` | Fetch UTxOs, protocol params, block info | `MaestroProvider`, `BlockfrostProvider` |
+| `Evaluator` | Evaluate Plutus script execution units | `OfflineTxEvaluator` |
+| `Submitter` | Submit signed transactions | `MaestroProvider`, `BlockfrostProvider` |
+
+## Chapters
+
+- [Serializer Backends](./di/serializers.md) — `TxBuildable` trait, WhiskyPallas vs WhiskyCSL
+- [Providers](./di/providers.md) — Fetcher, Evaluator, Submitter traits and implementations