# dusk-network/piecrust architecture

> Architecture diagram of the GitHub repository dusk-network/piecrust, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dusk-network/piecrust
- Repository: https://github.com/dusk-network/piecrust

## Overview

##### Project type and purpose
- This is a Rust **workspace** containing two primary crates plus example smart contracts:
– **piecrust**: a WebAssembly-based virtual machine (VM) for running Dusk smart contracts.
– **piecrust-uplink**: a software development kit (SDK) offering high-level Rust APIs (ABI, handlers, state helpers, serde support) for writing smart contracts that target the piecrust VM.
- The **contracts/** folder holds dozens of example smart-contract crates, compiled to WASM and exercised by the VM in tests.

##### File structure
- **Top-level crates:**
– `/piecrust`: VM source (instance, session, imports, store, commit, hashing, config, bytecode macro).
– `/piecrust-uplink`: SDK source (abi, handlers, helpers, state, serde support, types, error).
– `/contracts`: example smart contracts (each a small Rust crate producing a WASM payload).
- **Supporting crates:**
– `/crumbles`: (optional) external Merkle-tree datastore library.
– `/scripts`, `/Makefile`, `Cargo.toml`: build/test orchestration.
- **Key sub-directories in piecrust:**
– `src/imports`: WASM host-function implementations (wasm32/wasm64).
– `src/store`: pluggable data store modules (memory, commit_store, tree, index, metadata, module, session).
– `src/vm.rs`, `src/instance.rs`, `src/session.rs`: VM core.
– `src/bytecode_macro.rs`, `src/call_tree.rs`: compilation support.

##### Extract architecture details from the README
- Two workspace members and their responsibilities.
- Build & test process (Rust + wasm-tools).
- The VM runs, handles and creates Dusk smart contracts; the uplink crate sits “on top.”

##### Main components
a. **Smart Contracts (WASM Modules)**
– Compiled artifacts from `contracts/*`.
– Use `piecrust-uplink`’s ABI and macro support.
b. **piecrust-uplink SDK**
– **ABI Layer**: `abi.rs`, `handlers.rs` (imports host functions into WASM).
– **Helpers & State**: high-level Rust functions for contract logic.
– **Serde Support**: JSON/Borsh serialization of state.
c. **piecrust VM**
– **Instance**: `instance.rs` loads WASM, links imports.
– **Session**: `session.rs` manages execution context.
– **Store**: pluggable storage backends (`memory`, `commit_store`, `tree`, `index`, etc.).
– **Commit Store**: handles commit/finalize, uses hasher, treepos, module metadata.
– **Imports**: host-function implementations for syscalls.
d. **Persistence Layer**
– **On-Disk Datastore**: detailed in `docs/on-disk-datastore.md`.
– Could be backed by `crumbles` Merkle library.
e. **Build & Test Harness**
– Makefile, `wasm-tools`, `cargo`; CI workflows in `.github/workflows`.

##### Interactions and data-flow
1. **Developer** writes a Rust contract using **piecrust-uplink** APIs.
2. **Cargo build** + **wasm-tools** → produces WASM binary.
3. **piecrust VM** loads the WASM via the **Instance**, links uplink’s **ABI** imports.
4. On invocation, the **Session** executes functions, reading/writing through the **Store** API.
5. State changes are staged in **Commit Store**, hashed & serialized, then persisted to disk.
6. Optional: **crumbles** provides a Merkle-tree backend.
7. **Tests** under `piecrust/tests` & `piecrust-uplink/tests` automate end-to-end flows.

##### Architectural patterns & principles
- **Layered Architecture**: SDK → VM Core → Storage → Persistence.
- **Plugin-style Store**: separation of in-memory vs. persistent backends.
- **Host-Import Boundary**: WASM imports isolate contract logic from host environment.
- **Modular Crate Structure**: clear separation of ABI, handlers, commit logic.

##### Final checklist
[ ] All primary components (Contracts, SDK, VM, Store, Persistence, Test Harness) present
[ ] Labels of important modules (Instance, Session, Commit Store, ABI Handlers)
[ ] Callouts for build tools (Cargo, wasm-tools) and CI (GitHub Actions)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Smart Contracts
    SC["Smart Contracts (WASM Modules)"]:::contracts
    click SC "https://github.com/dusk-network/piecrust/tree/main/contracts/"

    %% SDK Layer
    subgraph "piecrust-uplink SDK"
        ABI["ABI Layer"]:::sdk
        Handlers["Host Handlers"]:::sdk
        Helpers["Helpers"]:::sdk
        State["State Helpers"]:::sdk
        Serde["Serde Support"]:::sdk
    end
    click ABI "https://github.com/dusk-network/piecrust/blob/main/piecrust-uplink/src/abi.rs"
    click Handlers "https://github.com/dusk-network/piecrust/blob/main/piecrust-uplink/src/abi/handlers.rs"
    click Helpers "https://github.com/dusk-network/piecrust/blob/main/piecrust-uplink/src/abi/helpers.rs"
    click State "https://github.com/dusk-network/piecrust/blob/main/piecrust-uplink/src/abi/state.rs"
    click Serde "https://github.com/dusk-network/piecrust/blob/main/piecrust-uplink/src/serde_support.rs"

    %% VM Core
    subgraph "piecrust VM"
        VMEntrypoint["VM Entrypoint"]:::vm
        Instance["Instance"]:::vm
        Session["Execution Session"]:::vm
        Imports["Host Imports"]:::vm
    end
    click VMEntrypoint "https://github.com/dusk-network/piecrust/blob/main/piecrust/src/vm.rs"
    click Instance "https://github.com/dusk-network/piecrust/blob/main/piecrust/src/instance.rs"
    click Session "https://github.com/dusk-network/piecrust/blob/main/piecrust/src/session.rs"
    click Imports "https://github.com/dusk-network/piecrust/blob/main/piecrust/src/imports/wasm32.rs"

    %% Store Abstraction
    subgraph "Store Abstraction"
        StoreAbst["Store Abstraction"]:::store
        CommitStore["Commit Store"]:::store
    end
    click StoreAbst "https://github.com/dusk-network/piecrust/blob/main/piecrust/src/store.rs"
    click CommitStore "https://github.com/dusk-network/piecrust/blob/main/piecrust/src/store/commit_store.rs"

    %% Persistence Layer
    subgraph "Persistence Layer"
        OnDisk["On-Disk Datastore Spec"]:::persist
        Merkle["Merkle Tree Backend"]:::persist
    end
    click OnDisk "https://github.com/dusk-network/piecrust/blob/main/docs/on-disk-datastore.md"
    click Merkle "https://github.com/dusk-network/piecrust/blob/main/crumbles/src/lib.rs"

    %% Build & Test Harness
    subgraph "Build & Test Harness"
        Orchestration["Orchestration (Makefile & Scripts)"]:::test
        CI["CI Workflows"]:::test
        VMTests["VM Tests"]:::test
        SDKTests["SDK Tests"]:::test
    end
    click Orchestration "https://github.com/dusk-network/piecrust/tree/main/scripts/"
    click CI "https://github.com/dusk-network/piecrust/blob/main/.github/workflows/build.yml"
    click VMTests "https://github.com/dusk-network/piecrust/tree/main/piecrust/tests/"
    click SDKTests "https://github.com/dusk-network/piecrust/blob/main/piecrust-uplink/tests/serde.rs"

    %% Data Flows
    SC -->|"compile + wasm-tools"| ABI
    Handlers -->|imports| VMEntrypoint
    ABI --> VMEntrypoint
    Helpers --> VMEntrypoint
    State --> VMEntrypoint
    Serde --> VMEntrypoint
    VMEntrypoint --> Instance
    Instance --> Session
    Session --> StoreAbst
    StoreAbst --> CommitStore
    CommitStore --> OnDisk
    CommitStore --> Merkle

    %% Build & Test Flows
    Orchestration -.-> SC
    Orchestration -.-> ABI
    Orchestration -.-> VMEntrypoint
    CI -.-> Orchestration
    VMTests -.-> VMEntrypoint
    VMTests -.-> CommitStore
    SDKTests -.-> ABI

    %% Styles
    classDef contracts fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef sdk fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef vm fill:#90EE90,stroke:#333,stroke-width:1px
    classDef store fill:#FFA500,stroke:#333,stroke-width:1px
    classDef persist fill:#A52A2A,stroke:#333,stroke-width:1px,color:#fff
    classDef test fill:#D3D3D3,stroke:#666,stroke-dasharray: 5 5,color:#000
```
