NOTICE Mar 1 2018: The atomic swap contract has been updated to specify the secret sizes to prevent fraudulent swaps between two cryptocurrencies with different maximum data sizes. Old contracts will not be usable by the new tools and vice-versa. Please rebuild all tools before conducting new atomic swaps.

Decred-compatible cross-chain atomic swapping

This repository contains utilities to manually perform cross-chain atomic swaps between various supported pairs of cryptocurrencies. At the moment, support exists for the following coins and wallets:

• Bitcoin (Bitcoin Core)
• Bitcoin Cash (Bitcoin ABC, Bitcoin Unlimited, Bitcoin XT)
• Decred (dcrwallet)
• Litecoin (Litecoin Core)
• Monacoin (Monacoin Core)
• Particl (Particl Core)
• Qtum (Qtum Core)
• Vertcoin (Vertcoin Core)
• Viacoin (Viacoin Core)
• Zcoin (Zcoin Core)

External support exists for the following coins and wallets:

• ThreeFold Token (ThreeFold Chain)

Pull requests implementing support for additional cryptocurrencies and wallets are encouraged. See GitHub project 1 for the status of coins being considered. Implementing support for a new cryptocurrency provides atomic swap compatibility between all current and future supported coins.

These tools do not operate solely on-chain. A side-channel is required between each party performing the swap in order to exchange additional data. This side-channel could be as simple as a text chat and copying data. Until a more streamlined implementation of the side channel exists, such as the Lightning Network, these tools suffice as a proof-of-concept for cross-chain atomic swaps and a way for early adopters to try out the technology.

Due to the requirements of manually exchanging data and creating, sending, and watching for the relevant transactions, it is highly recommended to read this README in its entirety before attempting to use these tools. The sections below explain the principles on which the tools operate, the instructions for how to use them safely, and an example swap between Decred and Bitcoin.

Build instructions

Requires Go 1.11 or later

• Clone atomicswap somewhere outside $GOPATH:

  $ git clone https://github.com/decred/atomicswap && cd atomicswap
  

• To install a single tool:

  $ cd cmd/dcratomicswap && go install
  

Theory

A cross-chain swap is a trade between two users of different cryptocurrencies. For example, one party may send Decred to a second party's Decred address, while the second party would send Bitcoin to the first party's Bitcoin address. However, as the blockchains are unrelated and transactions can not be reversed, this provides no protection against one of the parties never honoring their end of the trade. One common solution to this problem is to introduce a mutually-trusted third party for escrow. An atomic cross-chain swap solves this problem without the need for a third party.

Atomic swaps involve each party paying into a contract transaction, one contract for each blockchain. The contracts contain an output that is spendable by either party, but the rules required for redemption are different for each party involved.

One party (called counterparty 1 or the initiator) generates a secret and pays the intended trade amount into a contract transaction. The contract output can be redeemed by the second party (called counterparty 2 or the participant) as long as the secret is known. If a period of time (typically 48 hours) expires after the contract transaction has been mined but has not been redeemed by the participant, the contract output can be refunded back to the initiator's wallet.

For simplicity, we assume the initiator wishes to trade Bitcoin for Decred with the participant. The initiator can also trade Decred for Bitcoin and the steps will be the same, but with each step performed on the other blockchain.

The participant is unable to spend from the initiator's Bitcoin contract at this point because the secret is unknown by them. If the initiator revealed their secret at this point, the participant could spend from the contract without ever honoring their end of the trade.

The participant creates a similar contract transaction to the initiator's but on the Decred blockchain and pays the intended Decred amount into the contract. However, for the initiator to redeem the output, their own secret must be revealed. For the participant to create their contract, the initiator must reveal not the secret, but a cryptographic hash of the secret to the participant. The participant's contract can also be refunded by the participant, but only after half the period of time that the initiator is required to wait before their contract can be refunded (typically 24 hours).

With each side paying into a contract on each blockchain, and each party unable to perform their refund until the allotted time expires, the initiator redeems the participant's Decred contract, thereby revealing the secret to the participant. The secret is then extracted from the initiator's redeeming Decred transaction providing the participant with the ability to redeem the initiator's Bitcoin contract.

This procedure is atomic (with timeout) as it gives each party at least 24 hours to redeem their coins on the other blockchain before a refund can be performed.

The image below provides a visual of the steps each party performs and the transfer of data between each party.

<img src="workflow.svg" width="100%" height=650 />

Command line

Separate command line utilities are provided to handle the transactions required to perform a cross-chain atomic swap for each supported blockchain. For a swap between Bitcoin and Decred, the two utilities btcatomicswap and dcratomicswap are used. Both tools must be used by both parties performing the swap.

Different tools may require different flags to use them with the supported wallet. For example, btcatomicswap includes flags for the RPC username and password while dcratomicswap requires flags for TLS client authentication. Running a tool without any parameters will show the full usage help.

All of the tools support the same six commands. These commands are:

Commands:
  initiate <participant address> <amount>
  participate <initiator address> <amount> <secret hash>
  redeem <contract> <contract transaction> <secret>
  refund <contract> <contract transaction>
  extractsecret <redemption transaction> <secret hash>
  auditcontract <contract> <contract transaction>

initiate <participant address> <amount>

The initiate command is performed by the initiator to create the first contract. The contract is created with a locktime of 48 hours in the future. This command returns the secret, the secret hash, the contract script, the contract transaction, and a refund transaction that can be sent after 48 hours if necessary.

Running this command will prompt for whether to publish the contract transaction. If everything looks correct, the transaction should be published. The refund transaction should be saved in case a refund is required to be made later.

For dcratomicswap, this step prompts for the wallet passphrase. For the btcatomicswap and ltcatomicswap tools the wallet must already be unlocked.

participate <initiator address> <amount> <secret hash>

The participate command is performed by the participant to create a contract on the second blockchain. It operates similarly to initiate but requires using the secret hash from the initiator's contract and creates the contract with a locktime of 24 hours.

Running this command will prompt for whether to publish the contract transaction. If everything looks correct, the transaction should be published. The refund transaction should be saved in case a refund is required to be made later.

For dcratomicswap, this step prompts for the wallet passphrase. For the btcatomicswap and ltcatomicswap tools the wallet must already be unlocked.

redeem <contract> <contract transaction> <secret>

The redeem command is performed by both parties to redeem coins paid into the contract created by the other party. Redeeming requires the secret and must be performed by the initiator first. Once the initiator's redemption has been published, the secret may be extracted from the transaction and the participant may also redeem their coins.

Running this command will prompt for whether to publish the redemption transaction. If everything looks correct, the transaction should be published.

For dcratomicswap, this step prompts for the wallet passphrase. For the btcatomicswap and ltcatomicswap tools the wallet must already be unlocked.

refund <contract> <contract transaction>

The refund command is used to create and send a refund of a contract transaction. While the refund transaction is created and displayed during contract creation in the initiate and participate steps, the refund can also be created after the fact in case there was any issue sending the transaction (e.g. the contract transaction was malleated or the refund fee is now too low).

Running this command will prompt for whether to publish the redemption transaction. If everything looks correct, the transaction should be published.

extractsecret <redemption transaction> <secret hash>

The extractsecret command is used by