sb1752 / teleport-transactions

Taker and Maker protocol of an onchain atomic swap. This project includes a Taker library and a Maker binary with a working coinswap demo.

Teleport Transactions

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.

Table of Contents

• Table of Contents
• About
• Architecture
• Build and Run
• Project Status
• Roadmap
  • V 0.1.0
  • V 0.1.*
• Community

About

Teleport Transactions is a rust implementation of a variant of atomic-swap protocol, using HTLCs on Bitcoin. Read more at:

• Mailing list post
• Detailed design
• Developer's resources
• Run demo

Architecture

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.

Build and Run

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.

Project Status

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.

Roadmap

V 0.1.0

• 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.
• 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 a maker-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 and maker-cli in a downstream node.
• Release v0.1.0 in Signet for beta testing.

V 0.1.*

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

Contributing

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 TODOs in the codebase to find in-line marked code todos and smaller improvements.

Community

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.