# Cashu Nutshell **Cashu Nutshell is a Chaumian Ecash wallet and mint for Bitcoin Lightning. Cashu Nutshell is the reference implementation in Python.** Release Downloads Coverage *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](https://github.com/cashubtc/nuts)). Token logic based on [minicash](https://github.com/phyro/minicash) ([description](https://gist.github.com/phyro/935badc682057f418842c72961cf096c)) which implements a [Blind Diffie-Hellman Key Exchange](https://cypherpunks.venona.com/date/1996/03/msg01848.html) scheme written down [here](https://gist.github.com/RubenSomsen/be7a4760dd4596d06963d67baf140406).

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

### Feature overview of Nutshell - 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 ### Advanced features - 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 ## The Cashu protocol Different Cashu clients and mints use the same protocol to achieve interoperability. See the [documentation page](https://docs.cashu.space/) 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](https://github.com/cashubtc/nuts). ## Easy Install The easiest way to use Cashu is to install the package it via pip: ```bash 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](#using-cashu). ## 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 [Install Cashu](#poetry-install-cashu). #### Poetry: Prerequisites ```bash # 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.4 # install poetry curl -sSL https://install.python-poetry.org | python3 - echo export PATH=\"$HOME/.local/bin:$PATH\" >> ~/.bashrc source ~/.bashrc ``` #### Poetry: Install Cashu ```bash # install cashu git clone https://github.com/cashubtc/nutshell.git cashu cd cashu git checkout pyenv local 3.10.4 poetry install ``` #### Poetry: Update Cashu To update Cashu to the newest version enter ```bash 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 ```bash poetry shell ``` If you don't activate your environment, just prepend `poetry run` to all following commands. ## Configuration ```bash mv .env.example .env # edit .env file vim .env ``` To use the wallet with the [public test mint](#test-instance), 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 ```bash MINT_URL=https://testnut.cashu.space ``` # Using Cashu ```bash cashu info ``` This command shows information about your wallet. #### Check balance ```bash cashu balance ``` #### Generate a Lightning invoice This command will return a Lightning invoice that you need to pay to mint new ecash tokens. ```bash 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 --id `. #### Pay a Lightning invoice ```bash cashu pay lnbc120n1p3jfmdapp5r9jz... ``` #### Send tokens To send tokens to another user, enter ```bash 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: ```bash cashuAeyJwcm9vZnMiOiBbey... ``` #### Receive tokens To receive tokens, another user enters: ```bash cashu receive cashuAeyJwcm9vZnMiOiBbey... ``` # Starting the wallet API daemon Nutshell wallet can be used in daemon mode that can be controlled through a REST API: ```bash cashu -d ``` You can find the API docs at [http://localhost:4448/docs](http://localhost:4448/docs). # Running a mint This command runs the mint on your local computer. Skip this step if you want to use the [public test mint](#test-instance) instead. ## Docker ``` 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.16.0 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_PRIVATE_KEY` in your `.env` file. ```bash poetry run mint ``` For testing, you can use Nutshell without a Lightning backend by setting `MINT_BACKEND_BOLT11_SAT=FakeWallet` in the `.env` file. # Running tests To run the tests in this repository, first install the dev dependencies with ```bash poetry install --with dev ``` Then, make sure to set up your mint's `.env` file to use a fake Lightning backend and disable Tor: ```bash MINT_BACKEND_BOLT11_SAT=FakeWallet TOR=FALSE ``` You can run the tests with ```bash poetry run pytest tests ```