A collaborative attempt to document the tooling, steps and best practices for self-hosting or deploying a Cashu mint on all possible platforms. This is not a beginner-friednly guide, it assumes that the reader has some proficiency with git, deploying software and have access to an already running a functional Bitcoin node with a Lightning client (for mainnet deployments)
This guide only overviews currently a selection of clients that are available, not every single implementation that is out there.
If you wish to add a client to the following list then open an Issue on the github repository of this site.
This is provided for educational purposes only. Many of the clients listed in this guide are still in active development and carry substantial risk. Please advise that Cashu is in its early development, you should use the protocol only with small amounts of satoshis for testing and your first attempts at running a mint should be done on testnet/signet (not on mainnet Bitcoin) so that you can try it out without risking any satoshis.
Do your own research and ask questions in the appropriate support channels for the clients listed below.
For all the mint clients that are at your disposal to install, in the majority of cases the most painless option is to follow the Docker installation process for that client.
What is Docker?
Docker provides the ability to package and run an application in a loosely isolated environment called a container. The isolation and security lets you run many containers simultaneously on a given host. Containers are lightweight and contain everything needed to run the application, so you don't need to rely on what's installed on the host.
Read more about Docker here: https://docs.docker.com/guides/docker-overview
| Name | Languages | Platforms | Docker? | Latest release | Code | Guide |
|---|---|---|---|---|---|---|
| Nutshell | Python | All platforms | Yes | 0.15.3 | https://github.com/cashubtc/nutshell | Link to Guide |
| Moksha | Rust | Platforms | Yes | 0.2.1 | https://github.com/ngutech21/moksha | Link to Guide |
| gonuts | Go | All Platforms | No | 0.1.0 | https://github.com/elnosh/gonuts | Link to Guide |
| cashu-rs-mint | Rust, Nix | All Platforms | No | 🚧 | https://github.com/thesimplekid/cashu-rs-mint | Link to Guide |
| nutmix | Go | Platforms | Yes | 🚧 | https://github.com/lescuer97/nutmix | Link to Guide |
To complete any installation of a cashu mint on a Linux you will need the following technical proficiencies:
- knowledge of Bash / comfortable in a Terminal setting
- Root access to the machine that will be running the Mint
- Some knowledge of Lightning (node and channel management)
Covered in this guide are the following mainstream Linux distributions: Ubuntu, Debian, ...
ipsum lorem
ipsum lorem
ipsum lorem
Nutshell Cashu Nutshell is a Chaumian Ecash wallet and mint for Bitcoin Lightning. Cashu Nutshell is the reference implementation in Python.
Support channels for this Mint: https://github.com/cashubtc/nutshell/issues
Official Documentation: https://github.com/cashubtc/nutshell/blob/main/README.md
The easiest way to use Cashu is to install the package it via pip:
pip install cashuTo 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
git checkout <latest_tag>
pyenv local 3.10.4
poetry installIf 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 installCashu should be now installed. To execute the following commands, activate your virtual Poetry environment via
poetry shellIf you don't activate your environment, just prepend poetry run to all following commands.
mv .env.example .env
# edit .env file
vim .envTo 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 purposes and development only. The satoshis are not real.
Change the appropriate .env file settings to
MINT_URL=https://testnut.cashu.spaceBefore 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.
poetry run mintFor testing, you can use Nutshell without a Lightning backend by setting MINT_BACKEND_BOLT11_SAT=FakeWallet in the .env file.
...
...
pip install cashu
poetry run mint
...
...
TBC ....
TBC ....
TBC ....
Moksha moksha is a cashu library, mint and cli-wallet written in Rust.
Support channels for this Mint: https://github.com/ngutech21/moksha/issues
Official Documentation: https://github.com/ngutech21/moksha/blob/master/README.md
docker-compose simplifies the process of running multi-container Docker applications. Here's how you can use it to run the moksha -mint:
-
First, you need to have Docker Compose installed on your machine. If it's not installed, you can download it from the official Docker website.
-
Copy the tls.cert and admin.macaroon files from your LND instance into the
./data/mutinynet/directory. -
Configure the
LND_GRPC_HOSTenvironment variable in thedocker-compose.ymlfile to point to your LND instance. -
Run the following command in the same directory as your
docker-compose.ymlfile to start the mint and a postgres database:
docker-compose up -d app database...
...
docker-compose up -d app database
...
...
git clone https://github.com/ngutech21/moksha.git
cargo install just typos-cli sqlx-cli grcov wasm-pack wasm-opt
rustup component add llvm-tools-preview
cd mokshaThis is needed for the LND backend.
sudo apt install protobuf-compiler
brew install protobuf
choco install protocmv .env.example .env
# edit .env file
vim .envTo run the mint you need to setup a lightning regtest environment like Polar and a Lnbits or Lnd instance. In Lnbits create a new wallet and copy the admin key into the .env file and set the url to your Lnbits instance. The mint uses PostgreSQL for storing used proofs and pending invoices. The database URL can be configured in the .env file.
install docker and docker-compose
docker compose up -d
just db-create
just run-mint...
...
...
...
TBC ....
TBC ....
TBC ....
gonuts Cashu wallet and mint implementation in Go.
Support channels for this Mint: https://github.com/elnosh/gonuts/issues
Official Documentation: https://github.com/elnosh/gonuts/blob/main/README.md
With Go installed, you can run the following command to install the wallet:
go install github.com/elnosh/gonuts/cmd/nutw@latest
To setup a mint for the wallet, create a .env file at ~/.gonuts/wallet/.env and setup your preferred mint.
nutw balance
nutw mint 100
This will get an invoice from the mint which you can then pay and use to mint new ecash.
invoice: lnbc100n1pja0w9pdqqx...
nutw mint --invoice lnbc100n1pja0w9pdqqx...
nutw send 21
This will generate a Cashu token that looks like this:
cashuAeyJ0b2tlbiI6W3sibW...
This is the ecash that you can then send to anyone.
-
cd cmd/mint -
you'll need to setup a lightning regtest environment with something like Polar and fill in the values in the
.envfile -
go build -v -o mint mint.go -
./mint
...
...
go install github.com/elnosh/gonuts/cmd/nutw@latest
cd cmd/mint
go build -v -o mint mint.go
./mint
...
...
TBC ....
TBC ....
TBC ....
cashu-rs-mint Cashu mint using CDK
Support channels for this Mint: https://github.com/thesimplekid/cashu-rs-mint/issues
Official Documentation: https://github.com/thesimplekid/cashu-rs-mint/blob/main/README.md
nix develop
This will launch a nix shell with a regtest bitcoind node as well as two lightning nodes.
In order to use the node first a channel will need to be opened.
ln1 newaddr
ln2 newaddr
btc sendtoaddress <ln1 bitcoin address> 100
btc sendtoaddress <ln2 bitcoin address> 100
btc getnewaddress
btc generatetoaddress 50 <btc address>
Connect ln nodes
ln2 getinfo
ln1 connect <pubkey of ln1> 127.0.0.1 15352
Open a channel from ln1 to ln2
ln1 fundchannel id=<pubkey of ln2> amount=10000000
Open a channel from ln2 to ln1
ln1 getinfo
ln2 fundchannel id=<pubkey of ln1> amount=10000000
Generate blocks to confirm channels
btc getnewaddress
btc generatetoaddress 50 <btc address>
Start the mint, by default the mint will use ln1
cargo r
...
...
nix develop
ln1 newaddr
ln2 newaddr
btc sendtoaddress <ln1 bitcoin address> 100
btc sendtoaddress <ln2 bitcoin address> 100
btc getnewaddress
btc generatetoaddress 50 <btc address>
ln2 getinfo
ln1 connect <pubkey of ln1> 127.0.0.1 15352
ln1 fundchannel id=<pubkey of ln2> amount=10000000
ln1 getinfo
ln2 fundchannel id=<pubkey of ln1> amount=10000000
btc getnewaddress
btc generatetoaddress 50 <btc address>
cargo r
...
...
TBC ....
TBC ....
TBC ....
TBC ....
Nutmix golang implementation of ecash mint
Support channels for this Mint: https://github.com/lescuer97/nutmix/issues
Official Documentation: https://github.com/lescuer97/nutmix/blob/master/README.md
This project is thought to be able to be ran on a docker container or locally.
if you want to run the project in docker you will need two things.
You'll need the correct variables in an .env file. Use the env.example file as reference.
You need to make sure to use a strong POSTGRES_PASSWORD and make user the username and password are the same in the
DATABASE_URL
It's important to set up the variables under LIGHTNING CONNECTION for connecting to a node.
Please use a secure Private for deriving keysets.
if you want to run with docker traefik and you also need to fill variables below HOSTING for your domains.
If you have this correctly setup it should be as easy as running a simple docker command on linux:
If you missed and important variable for the mint. The mint should panic and let you know.
docker compose up -d
...
...
docker compose up -d
...
...
If you want to develop for the project I personally run a hybrid setup. I run the mint locally and the db on docker.
I have a special development docker compose called: docker-compose-dev.yml. This is for simpler development without having traefik in the middle.
- run the database in docker. Please check you have the necessary info in the
.envfile.
docker compose -f docker-compose-dev.yml up db
- Run the mint locally.
# build the project go run cmd/nutmix/*.go
...
...
docker compose -f docker-compose-dev.yml up db
# build the project go run cmd/nutmix/*.go
...
...
TBC ....
TBC ....
TBC ....
Yes. Cashu doesn't protect against network-level heuristics per default. Users should take precautions to protect themselves against leaking network metadata by using privacy tools such as Tor.
Each mint has their own tokens. Therefore, you cannot receive tokens from one mint into another mint. You can, however, use the tokens from one mint and swap them over Lightning for tokens from another mint. To transfer tokens from one mint to another, use the Multimint Swap functionality.
In your wallet client UI, use the Multimint Swap functionality, which operates via Lightning invoices under the hood.
- Cashu.me: On the Settings tab.
- Nutstash: On the Mint tab.
- eNuts: Go to Options->Mint Management->Funds->Multimint Swap
Note: You must have 2 mints in order to send/swap between mints.
You can use Bitcoin Mints to list, review, and find mints: https://bitcoinmints.com/
Listed below are the default mints in some of the Cashu wallet clients:
- Cashu.me: https://8333.space:3338
- Minibits: https://mint.minibits.cash
Yes, this is a common first test use case. Also, sometimes you might send a token that is not received or redeemed, and you might want to copy the token and receive it back to yourself.
Read this guide, try it out and contact the developer if you have issues or wish to contribute to the projects.
Yes.