Functioning, minimal-viable binaries and libraries to perform a trustless, p2p Maxwell-Belcher Coinswap Protocol.
The project is in active beta with experimental Mainnet use.
OpenSwap is a trustless, self-custodial atomic swap protocol built on Bitcoin. Unlike existing solutions that rely on centralized servers as single points of failure, OpenSwap's marketplace is seeded in the Bitcoin blockchain itself — no central host required, anyone with a Bitcoin node can participate.
For a quicker dive into the idea, see the Website.
Sybil resistance is achieved through Fidelity Bonds: time-locked UTXOs that make Sybil attacks economically costly while simultaneously bootstrapping the marketplace on-chain.
Two roles:
-
Makersare swap service providers. They earn swap fees for supplying liquidity, compete on fee rates in an open market, and signal reliability through larger fidelity bonds. Unlike Lightning nodes, maker servers need no active management — they run in install-fund-forget mode on any consumer hardware (Umbrel, Start9, Mynode, etc.), though liquidity must remain in the node's hot wallet to serve swap requests. -
Takersare clients initiating swaps. They pay all the fees (swap + mining), require no fidelity bond, and select makers based on bond validity, available liquidity, fee rates, and past swap history.
Multi-hop routing mirrors Lightning: swaps are routed through multiple makers, and no single maker sees the full route. The taker relays all messages between makers over Tor, keeping each maker's view partial. Protocol complexity lives entirely on the taker side, keeping maker servers lightweight. Users can choose to do either the legacy P2WSH, or more modern Taproot+Musig2 based atomic swap contracts.
The project extends Chris Belcher's teleport-transactions proof-of-concept into a production-grade implementation with full protocol handling, functional testing, sybil resistance, CLI tools, and a GUI app. The same protocol can be extended for cross-chain swaps.
For protocol-level details, see the OpenSwap Protocol Specifications.
For an in-depth exploration of the repository, it's recommended to use Deep Wiki.
This crate compiles into the following CLI binaries. Useful for integration testing, and dev environments.
makerd: A maker server daemon. Requires Bitcoin Core or an Electrum server, and Tor. Runs a maker daemon to handle swap requests.
maker-cli: CLI controller for the makerd. Manage server, access wallet, view swap statistics, and more. Demo
taker: A command-line OpenSwap client app to perform swaps, discover market, etc. Demo
Portal is a full-featured OpenSwap app, built directly on this crate's Rust APIs (taker api, maker api). It is a full wallet (receive, send, coin control, history) with swaps built in.
- Two roles: pick Wallet to swap your coins (the taker), or Router to provide liquidity and earn swap fees (the maker).
- Desktop or server: run it as a desktop app, or host it yourself as a server and reach it from a browser.
- Nothing else to install: it bundles its own Tor and defaults to a public Electrum server. You can point it at your own Bitcoin Core node instead.
- Same data as the CLI: its wallet data works with the OpenSwap CLI apps too.
Download a precompiled build from the releases page if one exists for your system, or build it from source. The demo doc walks through setup and a first swap.
For swapping between on-chain BTC and the Lightning Network — including routed swaps that need no Lightning node of your own — see lightning swaps.
For how wallet keys and passphrases are protected — at-rest encryption, in-memory key sealing, and the exact threat model — see wallet security.
Extensive functional testing simulates various protocol edge cases:
# needs nostr-rs-relay on PATH (cargo install nostr-rs-relay)
cargo test --features=integration-test -- --nocaptureThe Test Framework spawns toy marketplaces in Bitcoin regtest to test swap scenarios. Each test in tests/integration covers different edge cases. Start with standard_swap to understand programmatic simulation.
- Browse issues, especially
good first issue - Review open PRs
- Search for
TODOs in the codebase - Read the docs
- Read the Contributing Guide — including the AI contributions policy
The repo contains pre-commit githooks to do auto-linting before commits. Set up the pre-commit hook by running:
ln -s ../../git_hooks/pre-commit .git/hooks/pre-commitWe take the security of the protocol and its implementation seriously. If you discover a vulnerability, please report it responsibly.
Please do not open public GitHub issues for security vulnerabilities.
To report a security issue, email security@citadelfoss.xyz with a description of the vulnerability, steps to reproduce, and its potential impact. We will acknowledge your report and work with you on disclosure and remediation.
Dev community: Matrix
Dev discussions predominantly happen via FOSS best practices, and by using Github as the major community forum.
The Issues, PRs and Discussions are where all the hard lifting is happening.
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 the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.