Metadata-Version: 2.1
Name: cashu
Version: 0.8.0
Summary: Ecash wallet and mint for Bitcoin Lightning
Home-page: https://github.com/cashubtc/cashu
Author: Calle
Author-email: calle@protonmail.com
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: exceptiongroup (==1.1.0) ; python_version >= "3.7" and python_version < "3.11"
Requires-Dist: tomli (==2.0.1) ; python_version >= "3.7" and python_version < "3.11"
Requires-Dist: importlib-metadata (==6.0.0) ; python_version >= "3.7" and python_version < "3.8"
Requires-Dist: zipp (==3.11.0) ; python_version >= "3.7" and python_version < "3.8"
Requires-Dist: anyio (==3.6.2) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: attrs (==22.2.0) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: bech32 (==1.2.0) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: bitstring (==3.1.9) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: certifi (==2022.12.7) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: cffi (==1.15.1) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: charset-normalizer (==2.0.12) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: click (==8.0.4) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: cryptography (==36.0.2) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: ecdsa (==0.18.0) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: environs (==9.5.0) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: fastapi (==0.83.0) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: h11 (==0.12.0) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: idna (==3.4) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: iniconfig (==2.0.0) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: loguru (==0.6.0) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: marshmallow (==3.19.0) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: outcome (==1.2.0) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: packaging (==23.0) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: pluggy (==1.0.0) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: pycparser (==2.21) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: pycryptodomex (==3.16.0) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: pydantic (==1.10.4) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: pysocks (==1.7.1) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: pytest-asyncio (==0.19.0) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: pytest (==7.2.1) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: python-bitcoinlib (==0.11.2) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: python-dotenv (==0.21.0) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: represent (==1.6.0.post0) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: requests (==2.27.1) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: secp256k1 (==0.14.0) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: setuptools (==65.7.0) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: six (==1.16.0) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: sniffio (==1.3.0) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: sqlalchemy-aio (==0.17.0) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: sqlalchemy (==1.3.24) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: starlette (==0.19.1) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: typing-extensions (==4.4.0) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: urllib3 (==1.26.14) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: uvicorn (==0.18.3) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: websocket-client (==1.3.3) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: wheel (==0.38.4) ; python_version >= "3.7" and python_version < "4.0"
Requires-Dist: colorama (==0.4.6) ; python_version >= "3.7" and python_version < "4.0" and platform_system == "Windows" or python_version >= "3.7" and python_version < "4.0" and sys_platform == "win32"
Requires-Dist: win32-setctime (==1.1.0) ; python_version >= "3.7" and python_version < "4.0" and sys_platform == "win32"

# cashu  

**Cashu is a Chaumian Ecash wallet and mint for Bitcoin Lightning.**

<a href="https://pypi.org/project/cashu/"><img alt="Release" src="https://img.shields.io/pypi/v/cashu?color=black"></a> <a href="https://pepy.tech/project/cashu"> <img alt="Downloads" src="https://pepy.tech/badge/cashu"></a> <a href="https://app.codecov.io/gh/callebtc/cashu"><img alt="Coverage" src="https://img.shields.io/codecov/c/gh/callebtc/cashu"></a>


*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. 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 by Ruben Somsen [here](https://gist.github.com/RubenSomsen/be7a4760dd4596d06963d67baf140406). The database mechanics and the Lightning backend uses parts from [LNbits](https://github.com/lnbits/lnbits-legend).

<p align="center">
<a href="#cashu-client-protocol">Cashu client protocol</a> ·
<a href="#easy-install">Quick Install</a> ·
<a href="#hard-install-poetry">Manual install</a> ·
<a href="#configuration">Configuration</a> ·
<a href="#using-cashu">Using Cashu</a> ·
<a href="#running-a-mint">Run a mint</a>
</p>

### Feature overview

- Full Bitcoin Lightning support
- Standalone CLI wallet and mint server
- Mint library includable into other Python projects
- PostgreSQL and SQLite database support
- Builtin Tor for hiding IPs for wallet and mint interactions
- Multimint wallet for tokens from different mints
- Send tokens to nostr pubkeys

## Cashu client protocol
There are ongoing efforts to implement alternative Cashu clients that use the same protocol such as a [Cashu Javascript wallet](https://github.com/motorina0/cashu-js-wallet). If you are interested in helping with Cashu development, please see the [docs](docs/) for the notation and conventions used. 

## 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).

## Hard 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

# 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.9.13

# 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/callebtc/cashu.git --recurse-submodules
cd cashu
pyenv local 3.9.13
poetry install
```

#### Poetry: Update Cashu
To update Cashu to the newest version enter
```bash
git pull && poetry install
```
#### Poetry: Using Cashu

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 only. The server could vanish at any moment so consider any Satoshis you deposit a donation.*

Change the appropriate `.env` file settings to
```bash
MINT_HOST=8333.space
MINT_PORT=3338
```

# Using Cashu
```bash
cashu info
```

Returns:
```bash
Version: 0.8.0
Debug: False
Cashu dir: /home/user/.cashu
Wallet: wallet
Mint URL: https://8333.space:3338
```

#### 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 <amount> --hash <hash>`.

#### 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
W3siYW1vdW50IjogMSwgIkMiOiB7IngiOi...
```

You can now see that your available balance has dropped by the amount that you reserved for sending if you enter `cashu balance`:
```bash
Balance: 420 sat
```

#### Receive tokens
To receive tokens, another user enters:
```bash
cashu receive W3siYW1vdW50IjogMSwgIkMiOi...
```
You should see the balance increase:
```bash
Balance: 0 sat
Balance: 69 sat
```


# 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.
```bash
python -m cashu.mint
```

You can turn off Lightning support and mint as many tokens as you like by setting `LIGHTNING=FALSE` in the `.env` file.

