A Taker library with minimal API for performing coinswaps. A Maker binary with minimal config to deploy swap-service demons.
Warning
This library is currently under beta development and at an experimental stage. There are known and unknown bugs. Mainnet use is strictly NOT recommended.
Teleport Transactions is a rust implementation of a variant of atomic-swap protocol, using HTLCs on Bitcoin. Read more at:
The project is divided into distinct modules, each focused on specific functionalities.
docs/
src/
├─ bin/
├─ maker/
├─ market/
├─ protocol/
├─ scripts/
├─ taker/
├─ wallet/
├─ watchtower/
tests/
Directory | Description |
---|---|
doc |
Contains all the project-related docs. The dev-book includes major developer salient points and the demo doc describes how to run the teleport binary and perform a swap in regtest. |
tests |
Contains integration tests. Describes behavior of various abort/malice cases. |
src/taker |
Taker module houses its core logic in src/taker/api.rs and handles both Taker-related behaviors and most of the protocol-related logic. |
src/maker |
Encompasses Maker-specific logic and plays a relatively passive role compared to Taker. |
src/wallet |
Manages wallet-related operations, including storage and blockchain interaction. |
src/market |
Handles market-related logic, where Makers post their offers. |
src/watchtower |
Provides a Taker-offloadable watchtower implementation for monitoring contract transactions. |
src/scripts |
Offers simple scripts to utilize library APIs in the teleport app. |
src/bin |
Houses deployed project binaries. |
src/protocol |
Contains utility functions, error handling, and messages for protocol communication. |
The project follows the standard Rust build workflow and generates a CLI app named teleport
.
$ cargo build
The project includes both integration and unit tests. The integration tests simulates various edge cases of the coinswap protocol.
To run the tests:
$ cargo test -- --nocapture
For manual swaps using the teleport
app, follow the instructions in demo.
For in-depth developer documentation on protocol workflow and implementation, consult the dev book.
The project is currently in a pre-alpha stage, intended for demonstration and prototyping. The protocol has various hard-coded configuration variables and known/unknown bugs. Basic swap protocol functionality works on regtest
and signet
networks, but it's not recommended for mainnet
use.
If you're interested in contributing to the project, explore the open issues and submit a PR.
- Basic protocol workflow with integration tests.
- Modularize protocol components.
- Refine logging information.
- Abort 1: Taker aborts after setup. Makers identify this, and gets their fund back via contract tx.
- Abort 2: One Maker aborts before setup. Taker retaliates by banning the maker, moving on with other makers, if it can't find enough makers, then recovering via contract transactions.
- Case 1: Maker drops before sending sender's signature. Taker tries with another Maker and moves on.
- Case 2: Maker drops before sending sender's signature. Taker doesn't have any new Maker. Recovers from swap.
- Case 3: Maker drops after sending sender's signatures. Taker doesn't have any new Maker. Recovers from swap.
- Build a flexible Test-Framework with
bitcoind
backend. - Abort 3: Maker aborts after setup. Taker and other Makers identify this and recovers back via contract tx. Taker bans the aborting Maker's fidelity bond.
- Case 1: Maker Drops at
ContractSigsForRecvrAndSender
. Does not broadcasts the funding txs. Taker and Other Maker recovers. Maker gets banned. - Case 2: Maker drops at
ContractSigsForRecvr
after broadcasting funding txs. Taker and other Makers recover. Maker gets banned. - Case 3: Maker Drops at
HashPreimage
message and doesn't respond back with privkeys. Taker and other Maker recovers. Maker gets banned.
- Case 1: Maker Drops at
- Malice 1: Taker broadcasts contract immaturely. Other Makers identify this, get their funds back via contract tx.
- Malice 2: One of the Makers broadcast contract immaturely. The Taker identify this, bans the Maker's fidelity bond, other Makers get back funds via contract tx.
- Fix all clippy warnings.
- Implement configuration file i/o support for Takers and Makers.
- Switch to binary encoding for network messages.
- Switch to binary encoding for wallet data.
- Make tor detectable and connectable by default for Maker and Taker. And Tor configs to their config lists.
- Complete all unit tests in modules.
- Achieve >80% crate level test coverage ratio (including integration tests).
- Clean up and integrate fidelity bonds with maker banning.
- Sketch a simple
AddressBook
server. Tor must. This is for MVP. Later on we will move to more decentralized address server architecture. - Turn maker server into a
makerd
binary, and amaker-cli
rpc controller app, with MVP API. - Finalize the Taker API for downstream wallet integration.
- Develop an example web Taker client with a downstream wallet.
- Package
makerd
andmaker-cli
in a downstream node. - Release v0.1.0 in Signet for beta testing.
- Implement UTXO merging and branch-out via swap for improved UTXO management.
- Describe contract and funding transactions via miniscript, using BDK for wallet management.
- Enable wallet syncing via CBF (BIP157/158).
- Transition to taproot outputs for the entire protocol, enhancing anonymity and obfuscating contract transactions.
- Implement customizable wallet data storage (SQLite, Postgres).
- Optional: Payjoin integration via coinswap.
The project is under active development by a few motivated Rusty Bitcoin devs. Any contribution for features, tests, docs and other fixes/upgrades is encouraged and welcomed. The maintainers will use the PR thread to provide quick reviews and suggestions and are generally proactive at merging good contributions.
Few directions for new contributors:
-
The list of issues is a good place to look for contributable tasks and open problems.
-
Issues marked with
good first issue
are good places to get started for newbie Rust/Bitcoin devs. -
The docs are a good place to start reading up on the protocol.
-
Reviewing open PRs are a good place to start gathering a contextual understanding of the codebase.
-
Search for
TODO
s in the codebase to find in-line marked code todos and smaller improvements.
The dev community lurks in a small corner of Discord here (say holla, if you drop there from this readme).
Dev discussions predominantly happen via FOSS best practices, and by using Github as the Community Forum.
The Issues, PRs and Discussions are where all the hard lifting happening.