JoinMarket's coinjoin protocol over Nostr, beside JoinMarket's own onion directories and IRC, with Lightning channel opens, in Rust.
vortex-ng is the successor to LnVortex (archived 2022), rebuilt around JoinMarket's maker/taker market instead of a central coordinator:
- JoinMarket semantics, Nostr transport. The protocol layer (commands, NaCl sessions, PoDLE, fidelity bonds, per-pit transaction rules, maker and taker checks) follows JMP-0001 and the JMP extensions exactly. The message channel is Nostr relays. No coordinator.
- Beside JoinMarket's own channels (in progress, ADR 0007). The onion directory nodes and IRC that joinmarket-clientserver and JoinMarket-NG use, at the same time as Nostr, so vortex-ng shares their market; then a bridge for clients without Tor. Tracked in issue #33.
- Three pits.
sw0(P2WPKH, JMP-0001),tr0(taproot, JMP-0010), andwsh0(P2WSH 2-of-2, shaped exactly like a Lightning funding output; draft in this repo). - Lightning channel opens inside the coinjoin. A taker's equal-amount output can be the funding output of
a taproot channel (in
tr0) or a regular channel (inwsh0); makers see an ordinary output of the pit's type. LND, Core Lightning and LDK can open; any implementation can be the peer. - Upstreamable by construction. Every protocol piece JoinMarket lacks is written as a JMP draft
(
docs/jmp/) for joinmarket-ng to adopt.
Status: pre-release. CoinJoins work on regtest, over Nostr, and interoperate there with JoinMarket-NG. It is unaudited: mainnet wallets are refused. Do not use it with real funds.
docs/decisions/ |
Architecture decision records |
docs/jmp/jmp-draft-nostr-message-channel.md |
JoinMarket over Nostr: offers, public and private messages, relays, Tor |
docs/jmp/jmp-draft-wsh0-pit.md |
The wsh0 pit for regular Lightning channel opens |
docs/jmp/jmp-draft-channel-funding-outputs.md |
A taker's coinjoin output as a Lightning funding output |
docs/upstream-pins.md |
The JoinMarket revisions vortex-ng is compatible with |
| crate | role |
|---|---|
vortex-ng-core |
Protocol logic with no I/O: codec, nicks, offers, PoDLE, bonds, per-pit rules |
vortex-ng-nostr |
The Nostr message channel |
vortex-ng-wallet |
JoinMarket-compatible wallet (mixdepths per pit, fidelity bonds) |
vortex-ng-chain |
Chain backend over Core-compatible JSON-RPC (Bitcoin Core or rbitcoin) |
vortex-ng-ln |
Lightning channel funding (LND, Core Lightning, LDK) |
vortex-ng-maker, vortex-ng-taker |
The two roles |
vortex-ngd, vortex-ng-cli (binary vortex-ng) |
Daemon and command line |
M0 bootstrap + specs · M1 core (all pits, PoDLE, bonds, codec, test vectors) · M2 sw0 over Nostr, interop
with joinmarket-ng · M3 tr0 · M4 Lightning backends, wsh0, channel-funding outputs · M5 tumbler, channel
rings (JMP-0014), credential market (JMP-0012/13) · M6 external funding for Eclair and ldk-node upstream.
vortex-ng has the wallet commands, orderbook, maker, coinjoin and balance.
vortex-ng wallet new --wallet <file> --network <network> [--words 12|24] [--birthday <height>]
vortex-ng wallet restore --wallet <file> --network <network> [--mnemonic-file <file>]
[--bip39-passphrase | --bip39-passphrase-file <file>] [--birthday <height>]
vortex-ng wallet info --wallet <file>
vortex-ng wallet addresses --wallet <file> [--pit sw0|tr0|wsh0] [--mixdepth 0-4] [--count <n>] [--change]
vortex-ng wallet bond-address --wallet <file> --locktime <YYYY-MM>
vortex-ng orderbook --network <network> --relays <url[,url...]> [--pit sw0|tr0|wsh0] [--wait <seconds>] [node]
vortex-ng maker --wallet <file> --relays <url[,url...]> node (--fee-rel <fraction> | --fee-abs <sats>)
[--pit sw0|tr0|wsh0] [--txfee <sats>] [--min-size <sats>] [--max-size <sats>]
[--upkeep <seconds>]
vortex-ng coinjoin --wallet <file> --relays <url[,url...]> node --amount <sats> [--makers <n>]
[--mixdepth 0-4] [--destination <address>] [--pit sw0|tr0|wsh0]
[--fee-rate <sat/vB>] [--max-maker-fee <sats>] [--wait <seconds>]
[--allow-bondless-fees] [--yes]
vortex-ng balance --wallet <file> node [--pit sw0|tr0|wsh0]
node is --rpc-url <url> with --rpc-cookie-file <file> (or --rpc-user <name> and
--rpc-password-file <file>): a Bitcoin Core compatible node on the wallet's network.
- The wallet file holds the seed words encrypted under a password (Argon2id, AES-256-GCM-SIV; the format is
in
crates/vortex-ng-wallet/src/file.rs). It is created with mode 0600 and never overwritten. - Passwords and seed words are asked on the terminal without echo, or read from a file only its owner can
read (
--password-file,--mnemonic-file). They are never taken from the command line or the environment. - Networks:
regtest,signet,testnet4,testnet. Mainnet wallets are refused in this pre-release. - The words restore in joinmarket-ng too: same derivation paths (see
vortex-ng-wallet). makerruns until stopped. Every--upkeepseconds (30 by default) it brings the wallet up to the chain's tip and sizes its one offer to what the wallet can put into a round; it renews its announcement before it expires and withdraws it when there is too little to offer. Coins the node already shows as spent are never put into a round.coinjoindoes one CoinJoin as the taker, from one mixdepth to the next mixdepth of the same wallet or to--destination. It merges no more coins than the round needs, bounds each maker's fee (0.1 % of the amount and at least 2,000 sat unless--max-maker-feesays otherwise), takes makers without a fidelity bond only at a zero fee unless--allow-bondless-fees, shows what it is about to do and asks before sending anything (--yesskips the question). The transaction is checked with the node before it is broadcast.- Every PoDLE commitment sent is first written to
<wallet>.podle(the public value makers broadcast, one per line): a commitment is spent even by a round that fails, and each coin has three. orderbooklists what the makers on the relays answer, and verifies their fidelity bonds when given a node.orderbook,makerandcoinjointake--proxy <address>: a SOCKS5 proxy that isolates streams by username and password, such as a Tor daemon's SOCKS port (127.0.0.1:9050). Every nick then reaches the relays under credentials of its own, so Tor gives it circuits of its own: a maker and the throwaway nick it sends!hp2from share nothing. Relay names are resolved by the proxy, never on this machine. A proxy that takes no credentials could not keep nicks apart and is refused. Without--proxythe relays see this machine's address, and the command says so when it starts. In-process Tor (arti, featuretorofvortex-ng-nostr) is not wired into the commands yet.
Rust 1.98 (pinned in rust-toolchain.toml). cargo test --workspace.
vortex-ng exists because of the work it builds on:
- Ben Carman (benthecarman) and the LnVortex contributors, for showing that a coinjoin output can be a Lightning channel's funding output, and for the protocol and code that made the idea concrete.
- JoinMarket-NG and its contributors, for a clean, well-documented implementation of the JoinMarket protocol, the JMP specifications, and the taproot pit and channel-ring designs that vortex-ng follows; and the original JoinMarket project they build on.
Thank you.
Licensed under either of Apache License, Version 2.0 or MIT license at your option. Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.