🧠 Plutus Smart Contracts Setup Guide with Nix & Cabal

**Pheidippides — rapid Plutus Application Development (rPAD)**

Aim: To promote rapid, easy learning, simplification, and development on Cardano. Just like a Greek messenger Pheidippides, who ran to deliver good news of victory, rPAD aims to quickly deliver quick dApps to Cardano communities.

Welcome to the Plutus development onboarding guide! This document walks you through:

Installing Nix (with flakes + nix-command) on Ubuntu, Fedora, Arch, Windows WSL2, and Windows native
Entering a reproducible dev shell
Building with Cabal
Understanding the Vesting contracts and utilities

📂 NOTE: Detailed tutorials live in /code/wspace/lecture.

📚 Table of Contents

🧰 Prerequisites
⚙️ Environment Setup (Nix + Flakes)
- 2.1 Ubuntu
- 2.2 Fedora
- 2.3 Arch
- 2.4 Windows (WSL2)
- 2.5 Windows (Native)
- 2.6 Verify Your Setup
📦 Building the Project
📁 Folder Structure
🔍 Understanding the Contracts
- 5.1 Basic Vesting
- 5.2 Parameterized Vesting
🔧 Utilities Breakdown
🧪 Testing and Debugging
📖 Glossary of Terms
📝 License and Contributions

From Zero to Hero Haskell Plutus Flake.nix Template

Coming... Offchain Helios

1. 🧰 Prerequisites

Git CLI
Nix (we’ll install it below with flakes enabled)
Optional: VS Code + Haskell extension

2. ⚙️ Environment Setup (Nix + Flakes)

Start with # 🚀 NIX SETUP.md Tutorial (with Problems & Solutions) file in this directory

We recommend multi-user (daemon) installs on Linux and WSL2 for Windows. Flakes are enabled via NIX_CONFIG or /etc/nix/nix.conf.

🔧 Common shell snippet (Linux/WSL)

Add to ~/.bashrc (or ~/.zshrc) to always load Nix and enable flakes:

# Nix profile (added by me)
if [ -e /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh ]; then
  . /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh
elif [ -e "$HOME/.nix-profile/etc/profile.d/nix.sh" ]; then
  . "$HOME/.nix-profile/etc/profile.d/nix.sh"
fi

# Enable Nix experimental features for this shell
export NIX_CONFIG="experimental-features = nix-command flakes"

✅ System-wide alternative (Linux/WSL): Create /etc/nix/nix.conf (no need for the export above if you do this):
experimental-features = nix-command flakes

2.1 Ubuntu

Install (daemon):

sh <(curl -L https://nixos.org/nix/install) --daemon
. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh

Optional system-wide flakes:

sudo mkdir -p /etc/nix
echo 'experimental-features = nix-command flakes' | sudo tee /etc/nix/nix.conf

2.2 Fedora

SELinux is enabled by default. If the daemon won’t start, check journalctl -u nix-daemon.

Install (daemon):

sh <(curl -L https://nixos.org/nix/install) --daemon
. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh
sudo systemctl enable --now nix-daemon

Optional system-wide flakes:

sudo mkdir -p /etc/nix
echo 'experimental-features = nix-command flakes' | sudo tee /etc/nix/nix.conf

2.3 Arch

Install (daemon):

sh <(curl -L https://nixos.org/nix/install) --daemon
. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh
sudo systemctl enable --now nix-daemon

Optional system-wide flakes:

sudo mkdir -p /etc/nix
echo 'experimental-features = nix-command flakes' | sudo tee /etc/nix/nix.conf

2.4 Windows (WSL2)

Recommended Windows path for Plutus dev.

Enable systemd in WSL (once):

sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF

Then, in Windows PowerShell:

wsl --shutdown

Reopen Ubuntu (WSL).

Install (daemon) inside WSL:

sh <(curl -L https://nixos.org/nix/install) --daemon
. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh
sudo systemctl enable --now nix-daemon

Optional system-wide flakes (inside WSL):

sudo mkdir -p /etc/nix
echo 'experimental-features = nix-command flakes' | sudo tee /etc/nix/nix.conf

2.5 Windows (Native)

Native Nix on Windows is evolving. Prefer WSL2 if possible. If you proceed natively, enable flakes via PowerShell:

User-level persistent env:

setx NIX_CONFIG "experimental-features = nix-command flakes"

(Reopen PowerShell.)

Optional profile for immediate effect:

if (!(Test-Path $PROFILE)) { New-Item -Type File -Path $PROFILE -Force | Out-Null }
Add-Content $PROFILE '$env:NIX_CONFIG = "experimental-features = nix-command flakes"'

If you use Git Bash/MSYS, you can add the same Linux snippet to ~/.bashrc and adjust any profile paths installed by the native Nix package.

2.6 Verify Your Setup

nix --version
nix flake --help
nix doctor

On Linux/WSL:

systemctl status nix-daemon

3. 📦 Building the Project

a) Clone and Enter

git clone <your-repo-url>
cd plutus-nix

b) Enter the Dev Shell (flakes)

nix develop

If not using flakes:

nix-shell

c) Build with Cabal

cabal update
cabal build all

This builds both the Utilities library and the wspace smart contract/test modules.

4. 📁 Folder Structure

plutus-nix/
├── .devcontainer/
├── .vscode/
├── code/
│   ├── dist-newstyle/
│   ├── nix/
│   ├── Utilities/
│   │   ├── src/
│   │   │   └── Utilities/
│   │   │       ├── Conversions.hs
│   │   │       ├── PlutusTx.hs
│   │   │       ├── Serialise.hs
│   │   │       └── Utilities.hs
│   │   ├── Utilities.cabal
│   │   └── hie.yaml
│   ├── wspace/
│   │   ├── assets/
│   │   ├── lecture/
│   │   │   ├── CGPlutusUtilsv1.hs
│   │   │   ├── CGTime.hs
│   │   │   ├── ParameterizedVesting.hs
│   │   │   └── Vesting.hs
│   │   ├── test/
│   │   │   ├── CGPlutusUtilsSpec.hs
│   │   │   ├── CGTimeSpec.hs
│   │   │   ├── VestingSpec.hs
│   │   │   ├── ParameterizedVestingSpec.hs
│   │   │   ├── Spec.hs
│   │   │   └── Main.hs
│   │   ├── docs/
│   │   ├── Tutorials.md
│   │   ├── cabal.project
│   │   └── wspace.cabal
├── .gitignore
├── flake.nix
└── README.md

5. 🔍 Understanding the Contracts

5.1 Basic Vesting

File: lecture/Vesting.hs
Validates that:
- A transaction is signed by the beneficiary
- The deadline has been reached

5.2 Parameterized Vesting

File: lecture/ParameterizedVesting.hs
Accepts:
- beneficiary :: PubKeyHash
- deadline :: POSIXTime
Uses liftCode to embed these at compile time

6. 🔧 Utilities Breakdown

Address Utilities

File: lecture/CGPlutusUtilsv1.hs
- Decode Bech32 → PubKeyHash
- Encode PubKeyHash → Bech32 (mainnet/testnet)

Time Utilities

File: lecture/CGTime.hs
- POSIX, ISO8601, UTC conversions
- Time arithmetic: add/diff/getNow

7. 🧪 Testing and Debugging

Test Entry

main :: IO ()
main = defaultMain tests

Test Files

test/
├── CGPlutusUtilsSpec.hs
├── CGTimeSpec.hs
├── VestingSpec.hs
├── ParameterizedVestingSpec.hs
├── Spec.hs
└── Main.hs

Run tests via:

cabal test all

8. 📖 Glossary of Terms

Term	Description
POSIXTime	Seconds since the Unix epoch
PubKeyHash (PKH)	Hash of a wallet's public key
Validator	The on-chain logic for validation
ScriptContext	Transaction context during validation
liftCode / applyCode	Embeds values directly into compiled code
Bech32	Human-readable address format for Cardano
txSignedBy	Checks if a transaction is signed by a specific PKH
Utilities Library	Helper functions for off-chain dev/test
Cabal / Nix	Build and environment tools for Haskell & Plutus

🆕 Additional Glossary Terms

Term	Description
UTxO	Unspent transaction output, Cardano’s accounting model
Datum	On-chain data attached to UTxOs
GADT	Generalized Algebraic Data Type in Haskell
HRP	Human-Readable Part of a Bech32 string

9. 📝 License and Contributions

License

MIT License

Copyright (c) 2025 Women In Move Solutions (Pty) Ltd & Coxygen Global (Pty) Ltd
...

Author & Ownership

Author: Bernard Sibanda
Company: Coxygen Global (Pty) Ltd
Date: 27 September, 2025

Who is Bernard Sibanda? (Professional Intro omitted here for brevity; keep your original “Professional Introduction” section beneath this license block as-is.)

🔧 Troubleshooting (Quick)

nix flake unknown: Ensure your shell loaded the snippet or /etc/nix/nix.conf has experimental-features = nix-command flakes.
Daemon issues (Linux/WSL):
```
sudo systemctl status nix-daemon
journalctl -u nix-daemon -e
```
On WSL, confirm /etc/wsl.conf has systemd=true and you ran wsl --shutdown.
nix develop not found: You’re not on flakes; either enable flakes or use nix-shell.
Cabal can’t find GHC: Enter the Nix dev shell first (nix develop) so toolchains are pinned.

Name		Name	Last commit message	Last commit date
Latest commit History 53 Commits
.github/ISSUE_TEMPLATE		.github/ISSUE_TEMPLATE
.vscode		.vscode
code		code
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
NIX SETUP.md		NIX SETUP.md
README.md		README.md
REPLTutorial.md		REPLTutorial.md
SECURITY.md		SECURITY.md
Tutorials.md		Tutorials.md
default.nix		default.nix
flake.lock		flake.lock
flake.nix		flake.nix

Uh oh!

License

Uh oh!

wimsio/plutus-nix

Folders and files

Latest commit

History

Repository files navigation

🧠 Plutus Smart Contracts Setup Guide with Nix & Cabal

📚 Table of Contents

1. 🧰 Prerequisites

2. ⚙️ Environment Setup (Nix + Flakes)

Start with # 🚀 NIX SETUP.md Tutorial (with Problems & Solutions) file in this directory

🔧 Common shell snippet (Linux/WSL)

2.1 Ubuntu

2.2 Fedora

2.3 Arch

2.4 Windows (WSL2)

2.5 Windows (Native)

2.6 Verify Your Setup

3. 📦 Building the Project

a) Clone and Enter

b) Enter the Dev Shell (flakes)

c) Build with Cabal

4. 📁 Folder Structure

5. 🔍 Understanding the Contracts

5.1 Basic Vesting

5.2 Parameterized Vesting

6. 🔧 Utilities Breakdown

Address Utilities

Time Utilities

7. 🧪 Testing and Debugging

Test Entry

Test Files

8. 📖 Glossary of Terms

🆕 Additional Glossary Terms

9. 📝 License and Contributions

License

Author & Ownership

🔧 Troubleshooting (Quick)

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages