nutshell

Cashu Nutshell

Nutshell is a Chaumian Ecash wallet and mint for Bitcoin Lightning based on the Cashu protocol.

Cashu is a free and open-source Ecash protocol based on David Wagner’s variant of Chaumian blinding called Blind Diffie-Hellman Key Exchange scheme written down here.

Cashu protocol · Quick Install · Manual install · Configuration · Using Cashu · Run a mint

Feature overview

• Bitcoin Lightning support (LND, CLN, et al.)
• Full support for the Cashu protocol specifications
• Standalone CLI wallet and mint server
• Wallet and mint library you can include in other Python projects
• PostgreSQL and SQLite
• Wallet with builtin Tor
• Use multiple mints in a single wallet

Advanced features

• Deterministic wallet with seed phrase backup (NUT-13)
• Programmable ecash: P2PK and HTLCs (NUT-10)
• Wallet and mint support for keyset rotations
• DLEQ proofs for offline transactions (NUT-12)
• Response caching in memory or Redis (NUT-19)
• Optional authentication using Keycloak (NUT-21)

The Cashu protocol

Different Cashu clients and mints use the same protocol to achieve interoperability. See the documentation page for more information on other projects. If you are interested in developing on your own Cashu project, please refer to the protocol specs.

Easy Install: Nutshell wallet

Use Python 3.12 for installation. With Python 3.12 and pipx installed, run:

pipx install cashu --python python3.12
cashu --help

To update Cashu, use pipx upgrade cashu.

Alternatively, install with pip in a virtual environment:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install cashu
cashu --help

On Windows, use py -3.12 -m venv .venv and activate with .venv\Scripts\Activate.ps1 in PowerShell. For pipx, select the installed Python 3.12 executable with --python.

To update a pip installation, use python -m pip install --upgrade cashu.

Python 3.13/3.14 installations currently encounter Coincurve source-build failures: the version required by bip32 has no wheels for these interpreters. Selecting Python 3.12 avoids that build. Pipx uses its default interpreter unless you pass --python; it does not automatically switch to Python 3.12.

You can skip the entire next section about Poetry and jump right to Using Cashu.

Easy Install: Nutshell mint

The easiest way to get a mint running is through Docker.

You can build the image yourself by running the following command. Make sure to adjust the environment variables in docker-compose.yaml, and replace the public test MINT_MNEMONIC with your own.

docker compose up mint

Note: If you have a local .env file, it will be copied into the container and may override docker-compose environment variables. To ensure the mint is accessible from your host machine, either:

• Set MINT_LISTEN_HOST=0.0.0.0 in your .env file, or
• Use the pre-built Docker image command in the Running a mint section which sets environment variables directly.

Manual install: Poetry

These steps help you install Python via pyenv and Poetry. If you already have Poetry running on your computer, you can skip this step and jump right to Poetry: Install Cashu Nutshell.

Poetry: Prerequisites

# on ubuntu:
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

# install python using pyenv
curl https://pyenv.run | bash

# !! follow the instructions of pyenv init to setup pyenv !!
pyenv init

# restart your shell (or source your .rc file), then install python:
pyenv install 3.10

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

Poetry: Install Cashu Nutshell

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

Poetry: Update Cashu

To update Cashu to the newest version enter

git pull && poetry install

Poetry: Using the Nutshell wallet

Cashu should be now installed. To execute the following commands, activate your virtual Poetry environment via

poetry shell

If you don’t activate your environment, just prepend poetry run to all following commands.

Configuration

mv .env.example .env
# edit .env file
vim .env

To use the wallet with the public test mint, you need to change the appropriate entries in the .env file.

Test instance

Warning: this instance is just for demonstration purposes and development only. The satoshis are not real.

Change the appropriate .env file settings to

MINT_URL=https://testnut.cashu.space

Using Cashu

cashu info

This command shows information about your wallet.

Check balance

cashu balance

Generate a Lightning invoice

This command will return a Lightning invoice that you need to pay to mint new ecash tokens.

cashu invoice 420

The client will check every few seconds if the invoice has been paid. If you abort this step but still pay the invoice, you can use the command cashu invoice <amount> --id <id>.

Pay a Lightning invoice

cashu pay lnbc120n1p3jfmdapp5r9jz...

Send tokens

To send tokens to another user, enter

cashu send 69

You should see the encoded token. Copy the token and send it to another user such as via email or a messenger. The token looks like this:

cashuBo2F0gaJhaUgA2...

Receive tokens

To receive tokens, another user enters:

cashu receive cashuBo2F0gaJhaUgA2...

Running a mint

This command runs the mint on your local computer. Skip this step if you want to use the public test mint instead.

Docker

Run the mint using the pre-built Docker image. This method sets environment variables directly and works reliably regardless of local .env files:

docker run -d -p 3338:3338 --name nutshell -e MINT_BACKEND_BOLT11_SAT=FakeWallet -e MINT_LISTEN_HOST=0.0.0.0 -e MINT_LISTEN_PORT=3338 -e MINT_PRIVATE_KEY=TEST_PRIVATE_KEY cashubtc/nutshell:0.22.1 poetry run mint

From this repository

Before you can run your own mint, make sure to enable a Lightning backend in MINT_BACKEND_BOLT11_SAT and set MINT_MNEMONIC to a BIP-39 mnemonic in your .env file. The mint derives all of its keys from the mnemonic, so back it up securely: without it, the mint can’t start.

poetry run mint

For testing, you can use Nutshell without a Lightning backend by setting MINT_BACKEND_BOLT11_SAT=FakeWallet in the .env file.

Melt execution and recovery

Melt execution uses a renewable database lease. Its duration defaults to 60 seconds (MINT_MELT_LEASE_SECONDS), and execution has a 120-second budget (MINT_MELT_EXECUTION_TIMEOUT_SECONDS). Starting another worker preserves live leases. After a lease expires, status polling or periodic reconciliation can claim recovery without sending another payment.

Payments awaiting a definitive backend result remain pending. Before manual recovery, confirm that no executor can resume and verify the current payment outcome with the Lightning backend. To release execution ownership, use the management RPC command:

poetry run mint-cli update unlock-melt-quote <quote-id>

Unlocking retains the current quote and proof states. Reconciliation continues through the normal status polling and periodic recovery paths.

Stop all older workers before upgrading. Migration m042 adds lease expiry and payment uncertainty, treating existing pending payments as uncertain.

NUT-19 Response caching

Nutshell caches successful mint, swap, and melt responses in memory by default so wallets can recover lost responses (NUT-19). Redis can be enabled for shared caching across workers or instances. See Response caching for configuration and cache limits.

NUT-21 Authentication with Keycloak

Cashu supports clear and blind authentication as defined in NUT-21 and NUT-22 to limit the use of a mint to a registered set of users. Clear authentication is supported via an OIDC provider such as Keycloak. You can set up and run Keycloak instance using the docker compose file docker/keycloak/docker-compose.yml in this repository.

Migrate SQLite mint DB to Postgres

Use the standalone tool at cashu/mint/sqlite_to_postgres.py to migrate a mint database from SQLite to Postgres.

# 1) optionally reset the target Postgres database (DROPS ALL DATA)
psql -U <user> -h <host> -p <port> -d <database> -c "DROP SCHEMA public CASCADE; CREATE SCHEMA public; GRANT ALL PRIVILEGES ON SCHEMA public TO <user>;"

# 2) run migration (inside poetry env)
poetry run python cashu/mint/sqlite_to_postgres.py \
  --sqlite data/mint/mint.sqlite3 \
  --postgres postgres://<user>:<pass>@<host>:<port>/<database> \
  --batch-size 2000

• The tool aborts if the Postgres DB appears populated and prints the exact reset command with your connection details.
• After copying, it verifies row counts and compares the balance view across both databases.

Running tests

To run the tests in this repository, first install the dev dependencies with

poetry install --with dev

Then, make sure to set up your mint’s .env file to use a fake Lightning backend and disable Tor:

MINT_BACKEND_BOLT11_SAT=FakeWallet
TOR=FALSE

You can run the tests with

poetry run pytest tests

Contributing

Developers are invited to contribute to Nutshell. Please see the contribution guide.