Nutshell

liongrass / September 2025 (797 Words, 5 Minutes)

Ecash

Ecash is a privacy preserving cryptographically-secured form of electronic cash. It differs from Bitcoin in that anybody can issue their own ecash through what is called a mint. Users of a mint can send each other ecash without the issuer being able to trace the payments. When receiving ecash from untrusted mints, users typically instantly redeem the ecash for either Lightning payments, either into their own wallet, or for ecash in a mint they trust. In that way ecash is similar to a custodial Lightning wallet like LNbits, but hard for the issuer to track and audit.

Careful

Before running an ecash mint, be aware that due to the software’s inherent private nature, it can be difficult for you to audit your own mint, including the outstanding ecash. You are unable to control who your users are, how they transact and therefor may be unable to shut down your ecash mint without rugpulling your users.

Prerequisites

We assume you already have your Lightning node as set up through the Nodeacademy guides.

We’ll prepare our server by installing the required dependencies. Most of them should already be present if you followed these guides.

sudo apt install -y build-essential pkg-config libffi-dev libpq-dev zlib1g-dev libssl-dev python3-dev libsqlite3-dev ncurses-dev libbz2-dev libreadline-dev lzma-dev liblzma-dev

Next we are going to install pyenv

curl https://pyenv.run | bash

Once the script finishes running, you should see a Warning that you still haven’t added pyenv to your load path. You should be given a command like:

export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init - bash)"

Copy these lines and open ~/.profile using nano ~/.profile. Go to the very bottom and paste it there, then save and close the editor. Repeat for ~/.bashrc

Now exit your Terminal by typing exit and log back into your server.

We can now run pyenv init

Next we will install python 3.10 with the command:

pyenv install 3.10.4

We wiil now install poetry:

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

Installation

We can now proceed with the installation of the mint itself. Find out which version was released most recently by going to the projects github page.

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

Configuration

We are going to first copy the configuration file.

cp .env.example .env

The following lines are relevant:

MINT_PRIVATE_KEY= Generate a private key using the command openssl rand -hex 32 and enter it here. Don’t forget to remove the # sign at the beginning of the line.

MINT_BACKEND_BOLT11_SAT= Your best option is likely LndRestWallet, unless you also have LNbits installed, in which case LNbitsWallet may be more practical.

MINT_LND_REST_ENDPOINT=https://127.0.0.1:8086
MINT_LND_REST_CERT="/home/ubuntu/.lnd/tls.cert"
MINT_LND_REST_MACAROON="/home/ubuntu/.lnd/data/chain/bitcoin/regtest/admin.macaroon

Or if you choose to connect to LNbits, enter your LNbits endpoint and the admin key of a new blank wallet here:

MINT_LNBITS_ENDPOINT=https://legend.lnbits.com
MINT_LNBITS_KEY=yourkeyasdasdasd

Run Nutshell

In our ~/git/nutshell directory, we can now run nutshell with:

poetry env activate
poetry run mint

Keep your mint running in this stage, and continue in a new terminal window. We will later configure the mint to run automatically on startup.

Additional configuration

Optionally, you can also point a new domain name at your VPS, define a name for your Mint, add a description, contact email, add a message to the users or even add terms of service.

Make your mint publicly accessible

We are going to use Caddy as a reverse proxy. You might already have it installed when you configured LNbits.

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

Next, stop caddy and edit the configuration file, which may already exist on your system.

sudo caddy stop
sudo nano /etc/caddy/Caddyfile

At the very bottom, at this to your file. Don’t forget to replace your domain name.

ecash.nodeacademy.org {
	reverse_proxy 127.0.0.1:3338 {
		header_up X-Forwarded-Host ecash.nodeacademy.org
	}
}

Then start caddy:

sudo caddy start --config /etc/caddy/Caddyfile

You should now be able to add your mint to your ecash wallet.

Add Nutshell to Systemd

Next we will make sure nutshell starts up automatically when you reboot your machine.

We will create a systemd file.

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

We can paste the following:

# Systemd unit for lnbits
# /etc/systemd/system/nutshell.service

[Unit]
Description=Nutshell
# you can uncomment these lines if you know what you're doing
# it will make sure that nutshell starts after litd (replace with your own backend service)
Wants=litd.service
After=litd.service

[Service]
# replace with the absolute path of your nutshell installation
WorkingDirectory=/home/ubuntu/git/nutshell
# same here. run `which poetry` if you can't find the poetry binary
ExecStart=/home/ubuntu/.local/bin/poetry run mint
# replace with the user that you're running nutshell on
User=ubuntu
Restart=always
TimeoutSec=120
RestartSec=30
Environment=PYTHONUNBUFFERED=1

[Install]
WantedBy=multi-user.target

We can then activate the file with:

sudo systemctl enable --now nutshell.service

Now restart your machine and test whether Bitcoin Core, Litd, Nutshell and all other service start up properly.

You can follow the logs with:

journalctl -f -u nutshell.service