selfhost.directory

The index of self-hostable projects — ranked, categorized and served with live updates.
Own your data and stop giving it to big tech.

joinstr logo

Self-host joinstr

Nostr-coordinated CoinJoin pools for Bitcoin

BetaOpen Sourcemit
docker run --rm -p 127.0.0.1:5000:5000 -e JOINSTR_MANAGED=1 -e BITCOIN_RPC_URL=http://<node>:8332 -e BITCOIN_RPC_USER=<user> -e BITCOIN_RPC_PASS=<password> joinstr-web:dev
Updatedlast month
Setup difficultyAdvanced
Port
8000 (joinstrd REST API)
Requires
Bitcoin Core, Tor
joinstr web UI home pageCreate Pool form in the web UI

What is joinstr?

joinstr mixes bitcoin coins without a trusted hub: peers announce pools on ordinary nostr relays, each member signs their own input early with SIGHASH_ALL|ANYONECANPAY, and everyone verifies and then relays the finished transaction. Each pool fixes one denomination and a peer count of 2 to 10, and coordination traffic runs over Tor using isolated circuits, which keeps a relay from linking inputs to outputs by IP. This GitLab repository ships the Python side of the ecosystem — an Electrum plugin, a Flask-based web UI, a command line client and joinstrd, a loopback-only daemon exposing a REST API documented at /docs, /redoc and /openapi.json. To self-host it you need Python 3, a Bitcoin Core node with RPC and a local Tor proxy; the container build under contrib/docker packages its own Tor and opens the interface at TCP 5000, and that same Flask app is what the Umbrel app store distributes. Optional aut-ct keyset pools help defend against sybil attackers. Android, Sparrow and Rust clients are maintained in separate repositories; versioning is pre-1.0 but mainnet use is documented.

joinstr alternatives

All self-hosted alternatives to JoinMarket → All self-hosted alternatives to Wasabi Wallet (WabiSabi) → All self-hosted alternatives to Whirlpool (Samourai) →

Should you self-host joinstr?

joinstr scores 53/100 on selfhost.directory (how scoring works) and ranks #24 of 44 in Cryptocurrency.

There was no stable release in the past 12 months, so check the repository's recent activity before you rely on it.

Setup is advanced: plan for several services and some ongoing maintenance. It is mit-licensed.

Its closest alternative on selfhost.directory is Freqtrade (87/100, 56 935 stars). It scores higher overall, so compare the two before you pick. See joinstr vs Freqtrade side by side.

Features

  • CLI Client
  • Custom pool denomination and peer count
  • Hardware / air-gapped signing
  • Nostr relay coordination
  • OpenAPI documentation
  • REST API daemon
  • Resume interrupted pools
  • Ring signature drop-out recovery
  • Sybil resistance via aut-ctSupported in the Electrum plugin and Sparrow clients.
  • Web UI

How to install joinstr

Install joinstr with Docker

Environment variables
JOINSTR_MANAGED, BITCOIN_RPC_URL, BITCOIN_RPC_USER, BITCOIN_RPC_PASS, JOINSTR_WALLET
cd contrib/docker
docker build --build-arg JOINSTR_REF=$(git rev-parse HEAD) -t joinstr-web:dev .
docker run --rm -p 127.0.0.1:5000:5000 \
  -e JOINSTR_MANAGED=1 -e BITCOIN_RPC_URL=http://<node>:8332 \
  -e BITCOIN_RPC_USER=<user> -e BITCOIN_RPC_PASS=<password> \
  joinstr-web:dev

The container build lives in contrib/docker; the image runs Tor inside the container and serves the web UI on port 5000.

How to configure joinstr

  • BITCOIN_RPC_URLhttp://127.0.0.1:38332Node RPC URL (signet default; use port 8332 for mainnet)
  • BITCOIN_RPC_USERuserRPC user name
  • BITCOIN_RPC_PASSpassRPC password
  • TOR_PROXY127.0.0.1:9050Tor SOCKS5 proxy
  • JOINSTR_DATA_DIRthe gui directoryWhere pools and sessions are stored

FAQ

Where can I ask questions?

On the joinstr forum at forum.joinstr.xyz; bugs go to the issue tracker of the client you use.

Is there a fee for market makers?

No; joinstr currently has no makers and no coordinator fees.

Can a pool creator steal my coins?

No — your client checks the full transaction before signing and broadcasting and refuses rounds costing more than 15000 sats or inputs that could be broadcast alone.

What happens if a peer disappears in the middle of a round?

Before signing, the others can complete a smaller coinjoin via ring signature recovery; after signing nothing changes because every peer broadcasts the transaction.

Is the old Riseup VPN option still there?

Yes, as an option in the Electrum plugin and the Android app; a VPN pool makes every peer use the same Riseup gateway, with Tor still the default.

Do I need Tor?

Tor is the default and strongly recommended; the main clients refuse to reach a relay without it unless the pool uses the VPN transport.

Which relay should I use?

Any nostr relay accepting kind 2022 and kind 4 events; the default is wss://nos.lol and paid relays reduce spam.

How many peers should a pool have?

At least 2; more peers give a larger anonymity set but take longer to fill. The web UI allows 2 to 10.

What does a coinjoin cost?

Only the shared mining fee plus the premium your coin holds over the denomination; there is no coordinator fee, though a paid relay may charge.

Which denominations can I use?

Any — the pool creator chooses the denomination, and your coin must be worth that denomination plus 500 to 5000 sats since there is no change output.

Do I need to run Bitcoin Core?

Not necessarily: the Electrum plugin (and Sparrow) work with an Electrum server, while the web UI, daemon and Android app need Bitcoin Core.

Can I use joinstr on mainnet?

Yes; the Electrum plugin, web UI, daemon, Android app and Sparrow all work on mainnet, though a test round on Mutinynet or signet is suggested first.

More in Cryptocurrency

Rate this project

Click to rate — no account needed.

0 comments

Posting as guest
Loading comments…