⚠️ Don't be reckless: This project is in early development, it does however work with real sats! Always use amounts you don't mind loosing.

moksha

moksha is a cashu library, mint and cli-wallet written in Rust.

Contents

• About
• Progress
• Crates
• Usage
• License

About

Cashu is an Ecash implementation based on David Wagner's variant of Chaumian blinding. Token logic based on minicash (description) which implements a Blind Diffie-Hellman Key Exchange scheme written down by Ruben Somsen here. Please read the Cashu documentation for more detailed information.

Progress

Mint Features:

• Supported backends
  • LNbits
  • Lnd
  • Alby
  • Strike
  • core-lightning (WIP)

Wallet Features:

• connect to mint (load keys)
• request minting tokens
• minting tokens
• sending tokens (get an encoded token for chosen value)
• receiving tokens
• melting tokens
• check if tokens are spent
• multi mint support

Implemented NUTs:

• NUT-00
• NUT-01
• NUT-02
• NUT-03
• NUT-04
• NUT-05
• NUT-06
• NUT-07
• NUT-08
• NUT-09
• NUT-10
• NUT-11
• NUT-12
• NUT-13
• NUT-14
• NUT-15
• NUT-16
• NUT-17 on-chain mint (unofficial nut)
• NUT-18 on-chain melt (unofficial nut)

Crates

• moksha-core The core of the cashu library. Contains all the logic for creating and verifying tokens.
• moksha-wallet Cashu wallet library
• moksha-cli Cashu cli wallet
• moksha-mint Cashu mint server. Handles minting, melting and token requests.
• integrationtests Spins up a mint and runs integration tests against it.

Usage

Deploy mint

Docker-compose

docker-compose simplifies the process of running multi-container Docker applications. Here's how you can use it to run the moksha -mint:

1. 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.

2. Copy the tls.cert and admin.macaroon files from your LND instance into the ./data/mutinynet/ directory.

3. Configure the LND_GRPC_HOST environment variable in the docker-compose.yml file to point to your LND instance.

4. Run the following command in the same directory as your docker-compose.yml file to start the mint and a postgres database:

docker-compose up -d app database

Development

Setup rust

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 moksha

Install protobuf for your platform

This is needed for the LND backend.

sudo apt install protobuf-compiler
brew install protobuf
choco install protoc

Config

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

Run mint (cashu-server)

To 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

Run cli-wallet

Show info

Shows the current version, database-dir and mint-url.

just run-cli info

Check Balance

just run-cli balance

Mint tokens

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

just run-cli mint 42

Send tokens

To send tokens to another user, enter. The tokens will get printed to STOUT. You can then send them to the recipient via any messaging app.

just run-cli send 21

Receive tokens

To receive tokens you need to enter the token as first argument to the receive command. The tokens will get verified and the value will be added to your balance.

just run-cli receive cashuAeyJ0...

Development

To run coverage, check for typos etc. use the just commands:

Available recipes:
    build-docker   # build the mint docker-image
    build-wasm     # compile all rust crates, that are relevant for the client, to wasm
    clean          # clean cargo
    db-create      # creates the postgres database
    db-migrate     # runs sqlx prepare
    db-prepare     # runs sqlx prepare
    default        # list all tasks
    deps           # install all dependencies
    final-check    # format code, check typos and run tests
    publish        # publish everything on crates.io
    run-cli *ARGS  # run cli-wallet with the given args
    run-coverage   # run coverage
    run-itests     # run integrationtests
    run-mint *ARGS # run the cashu-mint
    run-tests      # runs all tests
    typos          # check code for typos
    typos-fix-all  # fix all typos

License

moksha is distributed under the terms of the MIT license. See LICENSE.