Cashu Nutshell – the eCash Mint

Cashu is an open-source protocol for ecash (digital coins), inspired by Chaumian eCash.
Goal: private, anonymous payments over the Bitcoin Lightning Network.

How it works

-> Users exchange Bitcoin via Lightning for eCash tokens at a so-called Mint (issuer).
-> These tokens are cryptographically blinded – the Mint cannot trace which tokens are later redeemed or transferred.
-> Tokens can be transferred, exchanged, or redeemed back for Lightning Bitcoin.

Nutshell is the reference implementation of Cashu in Python.

-> Includes the Mint server (issuing point for eCash) and clients.
-> Maintained by the Cashu community (Repo: cashubtc/nutshell).
-> Suitable both as an experimental platform and as a practical backend for wallets and apps.
-> With Nutshell you can start your own Mint and issue and receive eCash tokens.

Note

This tutorial uses an LNbits wallet as a funding source.
Other options – e.g. your personal Blink wallet – are also possible.

1. Basics

The foundation for this tutorial is an Ubuntu VPS. It is recommended to update and secure the system regularly.
As a reference, you can use chapters 2 and 3 of the Blitz⚡Bank documentation.

2. Install prerequisites

Update and install libraries

sudo apt update
sudo apt install -y \
  make build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
  libncurses5-dev libncursesw5-dev xz-utils tk-dev \
  libffi-dev liblzma-dev python3-openssl git

Install pyenv

curl https://pyenv.run | bash

Set path to pyenv

The path to pyenv is displayed at the end of the installation and must be added to the two files ~/.profile (for login shells) and ~/.bashrc (for interactive shells).

Note: Check the path used here once against the terminal output after installation.

echo -e "\n# pyenv path" >> ~/.profile
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.profile
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.profile
echo 'eval "$(pyenv init - bash)"' >> ~/.profile

echo -e "\n# pyenv path" >> ~/.bashrc
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init - bash)"' >> ~/.bashrc

-> Now reload the shell initialization files cleanly by logging out once with exit and logging back in.

Check if pyenv is active

pyenv versions

-> Output: * system (set by /home/user/.pyenv/version) ✅

Install Python

pyenv install 3.10.4

Install Poetry

Poetry is a Python ecosystem tool that manages dependencies (libraries) and virtual environments.

curl -sSL https://install.python-poetry.org | python3 - --version 1.8.5
echo export PATH=\"$HOME/.local/bin:$PATH\" >> ~/.bashrc
source ~/.bashrc

Check the installed version with: poetry -V

3. Install Nutshell

Check release: https://github.com/cashubtc/nutshell/releases

git clone https://github.com/cashubtc/nutshell.git nutshell
cd nutshell
git checkout <latest_tag>
pyenv local 3.10.4
poetry install

-> Check repository tag: git describe --tags
-> Check Nutshell version: poetry version
-> Check Poetry environment: poetry env info

Note, update Nutshell: git pull && poetry install

4. Configure Nutshell

Generate a private key for the Mint

openssl rand -hex 32

-> Store the key safely and then enter it under MINT_PRIVATE_KEY=.

LNbits as Nutshell backend wallet

Create an LNbits account with a wallet, retrieve the Admin key, and then enter it under MINT_LNBITS_KEY=.

Create and edit the .env configuration file

cp .env.example .env
nano ~/nutshell/.env

-> Edit MINT_PRIVATE_KEY=, MINT_LNBITS_ENDPOINT= and MINT_LNBITS_KEY=.
-> Set MINT_BACKEND_BOLT11_SAT= to LNbitsWallet.

5. Start Nutshell

Start once

poetry shell
poetry run mint

-> Starts the interactive shell in the virtual environment and then the Mint in the terminal.

Create system service

sudo nano /etc/systemd/system/nutshell.service

fill with:

[Unit]
Description=Nutshell
After=network.target

[Service]
WorkingDirectory=/home/user/nutshell
ExecStart=/home/user/.local/bin/poetry run mint
User=user
Restart=always
TimeoutSec=120
RestartSec=30
Environment=PYTHONUNBUFFERED=1

[Install]
WantedBy=multi-user.target

-> Adjust user and path if necessary!

Start and check system service

sudo systemctl enable nutshell
sudo systemctl start nutshell
sudo systemctl status nutshell
sudo journalctl -u nutshell -f --since "2 hour ago"

6. Caddy Webserver

Preparation: Point the domain / subdomain for Nutshell to the server’s IP address.

Install Caddy

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

Create Caddyfile

sudo nano /etc/caddy/Caddyfile

fill with:

# for nutshell mint
mint.yourdomain.com {
	reverse_proxy 127.0.0.1:3338 {
		header_up X-Forwarded-Host mint.yourdomain.com
	}
}

Reload Caddy once

sudo systemctl reload caddy

7. Cashu Wallets

The Mint is set up and active. It is now accessible to Cashu wallets under the domain mint.yourdomain.com.
Nothing is displayed on the website itself, but eCash wallets like Cashu.me, Minibits, or Macadamia can make use of it.

-> Macadamia.cash is for iOS,
-> Minibits.cash for Android,
-> Cashu.me is a web wallet that works on mobile devices and in the desktop browser.

The special thing about Cashu.me: It offers the possibility to be installed as a PWA (Progressive Web App). This allows the wallet to be “extracted” directly from the browser and displayed like a standalone app. It not only looks like an app but also behaves like one.

The link can be saved on the home screen or pinned to the taskbar. On mobile devices, the option to install the page as a PWA appears when you add it to the home screen. In Chrome, you will also find a small monitor symbol with an arrow in the corner at the far right of the address bar. If you hover over it, for example, it will say “Install Cashu.me”.

Once you have set up a Cashu wallet, you can manually add a Mint. An overview of various Mints can be found > here <.
For testing, you can also use my Mint – just send me a short message via one of the many channels.

Alternatively – and even easier: If you receive Cashu tokens, you can redeem them directly.
The token already contains the information about the Mint, and your wallet connects to it automatically. In the background, the token is redeemed, and from that point on, the coins belong to you and are stored on your device.

If the amount is significant enough that you would not want to lose it in the worst case, you should transfer it to your own Mint – or even better – withdraw it via Lightning into your own non-custodial Lightning wallet.

Thanks for reading!

8. Appendix

Useful links

cashubtc/nutshell – The Nutshell repository
awesome-cashu – Everything about Cashu on one page
bitcoinmints.com – Overview of different Mints with rating
nodeacademy.org/nutshell – A compendium for Nutshell with LND

Backup and Recovery

With Cashu wallets you often also get a seed phrase (12 words). This is the key to restore your tokens.
As far as I understand, an encrypted backup is stored on the Mint. The Mint has no access to the wallet; it only stores a bunch of cryptic data.

When you restore a wallet, you first get a new seed. However, with your backup seed you can restore the eCash tokens stored there. The tokens encrypted for you are then transferred to your new Cashu wallet. The backup seed is then used up and empty.

So for recovery you need: your seed and the information about which Cashu Mints you used.

---

Created with love 🧡 Since 917103 / 917109

---