How dusk-network/piecrust works
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)