Cashu Nutshell is a Chaumian Ecash wallet and mint for Bitcoin Lightning. Cashu Nutshell is the reference implementation in Python.
Disclaimer: The author is NOT a cryptographer and this work has not been reviewed. This means that there is very likely a fatal flaw somewhere. Cashu is still experimental and not production-ready.
Cashu is an Ecash implementation based on David Wagner's variant of Chaumian blinding (protocol specs). Token logic based on minicash (description) which implements a Blind Diffie-Hellman Key Exchange scheme written down here. The database mechanics in Cashu Nutshell and the Lightning backend uses parts from LNbits.
Cashu protocol · Quick Install · Manual install · Configuration · Using Cashu · Run a mint
- Bitcoin Lightning support
- Standalone Cashu CLI wallet and mint server
- Wallet and mint library to include in Python projects
- PostgreSQL and SQLite
- Wallet with builtin Tor
- Use multiple mints in one wallet
- Send and receive tokens on nostr
- Deterministic wallet with seed phrase backup
- Programmable ecash with, e.g., Pay-to-Pubkey support
- Wallet and mint support for keyset rotations
- DLEQ proofs for offline transactions
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 protocol specs.
The easiest way to use Cashu is to install the package it via pip:
pip install cashu
To update Cashu, use pip install cashu -U
.
If you have problems running the command above on Ubuntu, run sudo apt install -y pip pkg-config
and pip install wheel
. On macOS, you might have to run pip install wheel
and brew install pkg-config
.
You can skip the entire next section about Poetry and jump right to Using Cashu.
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 Install Cashu.
# 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
# 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.4
# install poetry
curl -sSL https://install.python-poetry.org | python3 -
echo export PATH=\"$HOME/.local/bin:$PATH\" >> ~/.bashrc
source ~/.bashrc
# install cashu
git clone https://github.com/cashubtc/nutshell.git cashu
cd cashu
pyenv local 3.10.4
poetry install
If you would like to use PostgreSQL as the mint database, use the command poetry install --extras pgsql
.
To update Cashu to the newest version enter
git pull && poetry install
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.
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.
Warning: this instance is just for demonstration only. The server could vanish at any moment so consider any Satoshis you deposit a donation.
Change the appropriate .env
file settings to
MINT_URL=https://8333.space:3338
cashu info
Returns:
Version: 0.14.0
Debug: False
Cashu dir: /home/user/.cashu
Wallet: wallet
Mint URL: https://8333.space:3338
cashu balance
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>
.
cashu pay lnbc120n1p3jfmdapp5r9jz...
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:
cashuAeyJwcm9vZnMiOiBbey...
You can now see that your available balance has dropped by the amount that you reserved for sending if you enter cashu balance
:
Balance: 420 sat
To receive tokens, another user enters:
cashu receive cashuAeyJwcm9vZnMiOiBbey...
You should see the balance increase:
Balance: 0 sat
Balance: 69 sat
Nutshell wallet can be used in daemon mode that can be controlled through a REST API:
cashu -d
You can find the API docs at http://localhost:4448/docs.
This command runs the mint on your local computer. Skip this step if you want to use the public test mint instead.
Before you can run your own mint, make sure to enable a Lightning backend in MINT_LIGHTNING_BACKEND
and set MINT_PRIVATE_KEY
in your .env
file.
poetry run mint
For testing, you can use Nutshell without a Lightning backend by setting MINT_LIGHTNING_BACKEND=FakeWallet
in the .env
file.
To run the tests in this repository, first install the dev dependencies with
poetry install --with dev
Then, make sure to set up your .env
file to use your local mint and disable Lightning and Tor:
LIGHTNING=FALSE
TOR=FALSE
You can run the tests with
poetry run pytest tests