Git-Mirrors/xmr-btc-swap
1
0
Fork 0
mirror of https://github.com/comit-network/xmr-btc-swap.git synced 2025-08-10 07:20:07 -04:00
Code Issues Projects Releases Packages Wiki Activity

refactor(docs): move source for doc pages here (#119)

Browse source 
* docs: move dev docs to dev-docs folder

* docs: move source for doc pages here

* docs: improve docs
This commit is contained in:
Einliterflasche 2024-10-25 03:55:18 +02:00 • committed by GitHub
parent 5341587dfa
commit bfc82c0534
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
46 changed files with 6307 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

3
docs/.gitignore vendored Normal file
View file

@ -0,0 +1,3 @@
.next
node_modules
.DS_Store

72
docs/Dockerfile Normal file
View file

@ -0,0 +1,72 @@
# Use the official Node.js 18 slim image as a base
FROM node:18-slim AS base
# Install dependencies only when needed
FROM base AS deps
WORKDIR /app
# Copy the lockfiles and package.json to install dependencies
COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* ./
RUN \
if [ -f yarn.lock ]; then yarn --frozen-lockfile; \
elif [ -f package-lock.json ]; then npm ci; \
elif [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm i --frozen-lockfile; \
else echo "Lockfile not found." && exit 1; \
fi
# Rebuild the source code only when needed
FROM base AS builder
WORKDIR /app
# Copy the installed node_modules and the rest of the app's source code
COPY --from=deps /app/node_modules ./node_modules
COPY . .
# Next.js collects completely anonymous telemetry data about general usage.
# Learn more here: https://nextjs.org/telemetry
# Uncomment the following line in case you want to disable telemetry during the build.
ENV NEXT_TELEMETRY_DISABLED 1
RUN \
if [ -f yarn.lock ]; then yarn run build; \
elif [ -f package-lock.json ]; then npm run build; \
elif [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm run build; \
else echo "Lockfile not found." && exit 1; \
fi
# Production image, copy all the files and run next
FROM base AS runner
WORKDIR /app
ENV NODE_ENV production
# Uncomment the following line in case you want to disable telemetry during runtime.
ENV NEXT_TELEMETRY_DISABLED 1
# Add a system group and user for running the app
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs
# Copy the public folder and the built .next folder
COPY --from=builder /app/public ./public
# Set the correct permission for prerender cache
RUN mkdir .next
RUN chown nextjs:nodejs .next
# Automatically leverage output traces to reduce image size
# https://nextjs.org/docs/advanced-features/output-file-tracing
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
# Switch to the new user
USER nextjs
# Expose the port that the app runs on
EXPOSE 3000
# Set the hostname
ENV HOSTNAME "0.0.0.0"
# server.js is created by next build from the standalone output
# https://nextjs.org/docs/pages/api-reference/next-config-js/output
CMD node server.js

6
docs/README.md
View file

@ -1,6 +0,0 @@
# Documentation
This directory hosts various pieces of documentation.
- [`swap` CLI](./cli/README.md)
- [`asb` service](./asb/README.md)

205
docs/asb/README.md
View file

@ -1,205 +0,0 @@
# Automated Swap Backend (ASB)
## Quick Start
From version `0.6.0` onwards the software default to running on `mainnet`.
It is recommended to try the software on testnet first, which can be achieved by providing the `--testnet` flag.
This quickstart guide assumes that you are running the software on testnet (i.e. Bitcoin testnet3 and Monero stagenet):
1. Download [latest release](https://github.com/comit-network/xmr-btc-swap/releases/latest) of the `asb` binary
2. Ensure that you have the Monero Wallet RPC running with `--wallet-dir` and `--disable-rpc-login`:
1. `monero-wallet-rpc --stagenet --daemon-host STAGENET-NODE-URL --rpc-bind-port STAGENET-NODE-PORT --disable-rpc-login --wallet-dir PATH/TO/WALLET/DIR`
3. Run the ASB in terminal: `./asb --testnet start`
4. Follow the setup wizard in the terminal
Public Monero nodes for running the Monero Wallet RPC can be found [here](https://community.rino.io/nodes.html).
Run `./asb --help` for more information.
### Running on mainnet
For running the ASB on mainnet you will have to change you `monero-wallet-rpc` setup to mainnet.
It is recommended that you run your own Monero and Bitcoin node when running on mainnet.
It is possible to plug into public blockchain nodes but be aware that you might lose some privacy doing so.
Public Monero mainnet nodes can be found [here](https://moneroworld.com/#nodes).
Public Electrum mainnet nodes can be found [here](https://1209k.com/bitcoin-eye/ele.php?chain=btc).
## ASB Details
The ASB is a long running daemon that acts as the trading partner to the swap CLI.
The CLI user is buying XMR (i.e. receives XMR, sends BTC), the ASB service provider is selling XMR (i.e. sends XMR, receives BTC).
The ASB can handle multiple swaps with different peers concurrently.
The ASB communicates with the CLI on various [libp2p-based](https://libp2p.io/) network protocols.
Both the ASB and the CLI can be run by anybody.
The CLI is designed to run one specific swap against an ASB.
The ASB is designed to run 24/7 as a daemon that responds to CLIs connecting.
Since the ASB is a long running task we specify the person running an ASB as service provider.
### ASB discovery
The ASB daemon supports the libp2p [rendezvous-protocol](https://github.com/libp2p/specs/tree/master/rendezvous).
Usage of the rendezvous functionality is entirely optional.
You can configure one or more rendezvous points in the `[network]` section of your config file.
For the registration to be successful, you also need to configure the externally reachable addresses within the `[network]` section.
For example:
```toml
[network]
rendezvous_point = [
"/dns4/discover.unstoppableswap.net/tcp/8888/p2p/12D3KooWA6cnqJpVnreBVnoro8midDL9Lpzmg8oJPoAGi7YYaamE",
"/dns4/eratosthen.es/tcp/7798/p2p/12D3KooWAh7EXXa2ZyegzLGdjvj1W4G3EXrTGrf6trraoT1MEobs",
]
external_addresses = ["/dns4/example.com/tcp/9939"]
```
For more information on the concept of multiaddresses, check out the libp2p documentation [here](https://docs.libp2p.io/concepts/addressing/).
In particular, you may be interested in setting up your ASB to be reachable via a [`/dnsaddr`](https://github.com/multiformats/multiaddr/blob/master/protocols/DNSADDR.md) multiaddress.
`/dnsaddr` addresses provide you with flexibility over the port and also allow you to register two addresses with transports (with and without websockets for example) under the same name.
### Setup Details
In order to understand the different components of the ASB and CLI better here is a component diagram showcasing the ASB and CLI setup using public Bitcoin and Monero infrastructure:
![Service Provider scenarios](http://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.githubusercontent.com/comit-network/xmr-btc-swap/363ce1cdf6fe6478736ff91e1458d650c2319248/docs/asb/diagrams/cli-asb-components-asb-pub-nodes.puml)
Contrary, here is a diagram that showcases a service provider running it's own blockchain infrastructure for the ASB:
![Service Provider scenarios](http://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.githubusercontent.com/comit-network/xmr-btc-swap/363ce1cdf6fe6478736ff91e1458d650c2319248/docs/asb/diagrams/cli-asb-components-asb-self-hosted.puml)
The diagram shows that the `asb` group (representing the `asb` binary) consists of three components:
1. Monero Wallet
2. Bitcoin Wallet
3. ASB
The `ASB` depicted in the diagram actually consists of multiple components (protocol impl, network communication, ...) that sums up the functionality to execute concurrent swaps in the role of Alice.
#### Monero Wallet Setup
The ASB uses the running Monero wallet RPC to create / open Monero wallets.
Currently you cannot connect to an existing Monero wallet, but the ASB will create the wallet `asb-wallet` upon intial startup.
In order to accept trades with a CLI you will have to send XMR to that wallet.
The wallet's address is printed upon startup of the ASB.
Currently the `asb-wallet` does not have a password.
Upon startup of the ASB the `asb-wallet` is opened in the wallet RPC.
You can then interact with the wallet RPC for basic wallet management as well.
#### Bitcoin Wallet Setup
The ASB has an internally managed Bitcoin wallet.
The Bitcoin wallet is created upon initial startup and stored in the data folder of the ASB (configured through initial startup wizard).
#### Market Making
For market making the ASB offers the following parameters in the config:
```toml
[maker]
min_buy_btc = 0.0001
max_buy_btc = 0.0001
ask_spread = 0.02
price_ticker_ws_url = "wss://ws.kraken.com"
```
The minimum and maximum amount as well as a spread, that is added on top of the price fetched from a central exchange, can be configured.
In order to be able to trade, the ASB must define a price to be able to agree on the amounts to be swapped with a CLI.
The `XMR<>BTC` price is currently determined by the price from the central exchange Kraken.
Upon startup the ASB connects to the Kraken price websocket and listens on the stream for price updates.
You can plug in a different price ticker websocket using the `price_ticker_ws_url` configuration option.
You will have to make sure that the format returned is the same as the format used by Kraken.
Currently, we use a spot-price model, i.e. the ASB dictates the price to the CLI.
A CLI can connect to the ASB at any time and request a quote for buying XMR.
The ASB then returns the current price and the minimum and maximum amount tradeable.
#### Swap Execution
Swap execution within the ASB is automated.
Incoming swaps request will be automatically processed, and the swap will execute automatically.
Swaps where Bob does not act, so Alice cannot redeem, will be automatically refunded or punished.
If the ASB is restarted unfinished swaps will be resumed automatically.
The refund scenario is a scenario where the CLI refunds the Bitcoin.
The ASB can then refund the Monero which will be automatically transferred back to the `asb-wallet`.
The punish scenario is a scenario where the CLI does not refund and hence the ASB cannot refund the Monero.
After a second timelock expires the ASB will automatically punish the CLI user by taking the Bitcoin.
More information about the protocol in this [presentation](https://youtu.be/Jj8rd4WOEy0) and this [blog post](https://comit.network/blog/2020/10/06/monero-bitcoin).
All claimed Bitcoin ends up in the internal Bitcoin wallet of the ASB.
The ASB offers a commands to withdraw Bitcoin and check the balance, run `./asb --help` for details.
If the ASB has insufficient Monero funds to accept a swap the swap setup is rejected.
Note that there is currently no notification service implemented for low funds.
The ASB provider has to monitor Monero funds to make sure the ASB still has liquidity.
#### Tor and hidden services
The ASB supports Tor and will automatically create a Tor hidden service if the Tor control port can be found.
By default, the ASB will look for the control port under `localhost:9051`.
To allow the ASB to create a hidden service, enable the control port and authentication in your torrc file:
```
ControlPort 9051
CookieAuthentication 1
CookieAuthFileGroupReadable 1
```
It is important that the user running the ASB has the correct user rights, i.e. is in the same group as the user running Tor.
E.g. if running on debian and having Tor install via apt, add your user to the following group:
`sudo adduser $(whoami) debian-tor`.
When configured correctly, your ASB will print the created onion addresses upon startup:
```bash
./bin/asb start
May 01 01:31:27.602 INFO Initialized tracing with level: debug
...
May 01 01:32:05.018 INFO Tor found. Setting up hidden service.
May 01 01:32:07.475 INFO /onion3/z4findrdwtfbpoq64ayjtmxvr52vvxnsynerlenlfkmm52dqxsl4deyd:9939
May 01 01:32:07.476 INFO /onion3/z4findrdwtfbpoq64ayjtmxvr52vvxnsynerlenlfkmm52dqxsl4deyd:9940
```
### Exporting the Bitcoin wallet descriptor
First use `swap` or `asb` with the `export-bitcoin-wallet` subcommand.
Output example:
```json
{
"descriptor": "wpkh(tprv8Zgredacted.../84'/1'/0'/0/*)",
"blockheight": 2415616,
"label": "asb-testnet"
}
```
The wallet can theoretically be directly imported into
[bdk-cli](https://bitcoindevkit.org/bdk-cli/installation/) but it is easier to
use Sparrow Wallet.
Sparrow wallet import works as follows:
- File -> New wallet -> Give it a name
- Select "New or Imported Software Wallet"
- Click "Enter Private Key" for "Master Private Key (BIP32)"
- Enter the `xprv...` or `tprv...` part of the descriptor (example above is `tprv8Zgredacted...`:
![image](enter-master-private-key.png)
- Click "Import"
- Leave the derivation path as `m/84'/0'/0'` and click "Import Keystore" button
- Click "Apply" and then supply password
![image](import-keystore.png)
- Click Transactions tab
- ???
- Profit!
![image](transactions-tab.png)

57
docs/asb/diagrams/cli-asb-components-asb-pub-nodes.puml
View file

@ -1,57 +0,0 @@
@startuml
package "User Host" {
component [Monero Wallet RPC\n(auto installed)] as CliMonRpc
() RPC as MonRpcCli
component "swap" {
component [CLI] as CLI
component [Bitcoin Wallet] as CliBitWal
}
CliMonRpc - MonRpcCli
CLI - CliBitWal
MonRpcCli - CLI
}
package "Public Monero Server" {
component "monerod" as Monerod
}
package "Public Bitcoin Server" {
component "Electrum Server" as Electrum
component "bitcoind" as Bitcoind
() "RPC" as BitRPC
BitRPC -- Electrum
Electrum - Bitcoind
}
package "Service Provider Host" {
component [Monero Wallet RPC] as AsbMonRpc
() RPC as MonRpcAsb
component "asb" {
component [ASB] as ASB
component [Bitcoin Wallet] as AsbBitWal
}
AsbMonRpc - MonRpcAsb
ASB - AsbBitWal
MonRpcAsb - ASB
}
package "Public Price Server" {
component [CEX Price Ticker] as CEX
() "websocket" as Ticker
Ticker - CEX
Ticker -- ASB
}
CliBitWal -- BitRPC
CliMonRpc -- Monerod
AsbMonRpc -- Monerod
AsbBitWal -- BitRPC
() "libp2p" as Libp2p
Libp2p -- CLI
ASB -- Libp2p
footer XMR<>BTC swap CLI & ASB overview (public nodes)\nRendered with PlantUML version %version()
@enduml

67
docs/asb/diagrams/cli-asb-components-asb-self-hosted.puml
View file

@ -1,67 +0,0 @@
@startuml
package "User Host" {
component [Monero Wallet RPC\n(auto installed)] as CliMonRpc
() RPC as MonRpcCli
component "swap" {
component [CLI] as CLI
component [Bitcoin Wallet] as CliBitWal
}
CliMonRpc - MonRpcCli
CLI - CliBitWal
MonRpcCli - CLI
}
package "Public Monero Server" {
component "monerod" as Monerod
}
package "Public Bitcoin Server" {
component "Electrum Server" as Electrum
component "bitcoind" as Bitcoind
() "RPC" as BitRPC
BitRPC -- Electrum
Electrum - Bitcoind
}
package "Service Provider Host" {
component [Monero Wallet RPC] as AsbMonRpc
() RPC as MonRpcAsb
component "asb" {
component [ASB] as ASB
component [Bitcoin Wallet] as AsbBitWal
}
AsbMonRpc - MonRpcAsb
component "monerod" as AsbMonerod
component "Electrum Server" as AsbElectrum
component "bitcoind" as AsbBitcoind
AsbMonRpc -- AsbMonerod
() "RPC" as AsbBitRPC
AsbBitWal -- AsbBitRPC
AsbBitRPC -- AsbElectrum
AsbElectrum - AsbBitcoind
ASB - AsbBitWal
ASB -- MonRpcAsb
}
package "Public Price Server" {
component [CEX Price Ticker] as CEX
() "websocket" as Ticker
Ticker - CEX
Ticker -- ASB
}
CliBitWal -- BitRPC
CliMonRpc -- Monerod
() "libp2p" as Libp2p
Libp2p -- CLI
ASB -- Libp2p
footer XMR<>BTC swap CLI & ASB overview\nRendered with PlantUML version %version()
@enduml

34
docs/asb/diagrams/cli-asb-overview.puml
View file

@ -1,34 +0,0 @@
@startuml
package "Service Provider 1" {
rectangle CLI as cli01
rectangle CLI as cli02
rectangle CLI as cli03
rectangle ASB as asb01
note right of asb01
Service provider
advertising to
multiple users.
end note
cli01 -> asb01
cli02 --> asb01
asb01 <-- cli03
}
package "Service Provider 2" {
rectangle CLI as cli04
rectangle ASB as asb02
note right of asb02
Service provider
advertising to
one single users.
end note
cli04 -> asb02
}
@enduml

BIN
docs/asb/enter-master-private-key.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 35 KiB

BIN
docs/asb/import-keystore.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 182 KiB

BIN
docs/asb/transactions-tab.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 109 KiB

141
docs/cli/README.md
View file

@ -1,141 +0,0 @@
# Swap CLI
The CLI defaults to **mainnet** (from version 0.6.0 onwards).
For testing and to familiarise yourself with the tool, we recommend you to try it on testnet first.
To do that, pass the `--testnet` flag with the actual command:
```shell
swap --testnet <SUBCOMMAND>
```
Take note that applying `--testnet` results in transacting on Bitcoin testnet and on Monero stagenet, not on Monero testnet.
The two main commands of the CLI are:
- `buy-xmr`: for swapping BTC to XMR with a particular seller
- `list-sellers`: for discovering available sellers through a rendezvous point
Running `swap --help` gives us roughly the following output:
```
swap 0.8.0
The COMIT guys <hello@comit.network>
CLI for swapping BTC for XMR
USAGE:
swap [FLAGS] [OPTIONS] <SUBCOMMAND>
FLAGS:
--debug Activate debug logging
-h, --help Prints help information
-j, --json Outputs all logs in JSON format instead of plain text
--testnet Swap on testnet and assume testnet defaults for data-dir and the blockchain related parameters
-V, --version Prints version information
OPTIONS:
--data-base-dir <data> The base data directory to be used for mainnet / testnet specific data like database, wallets etc
SUBCOMMANDS:
buy-xmr Start a BTC for XMR swap
list-sellers Discover and list sellers (i.e. ASB providers)
cancel Try to cancel an ongoing swap (expert users only)
help Prints this message or the help of the given subcommand(s)
history Show a list of past, ongoing and completed swaps
refund Try to cancel a swap and refund the BTC (expert users only)
resume Resume a swap
```
## Swapping BTC for XMR
Running `swap buy-xmr --help` gives us roughly the following output:
```
swap-buy-xmr 0.8.0
Start a BTC for XMR swap
USAGE:
swap buy-xmr [FLAGS] [OPTIONS] --change-address <bitcoin-change-address> --receive-address <monero-receive-address> --seller <seller>
FLAGS:
-h, --help Prints help information
--testnet Swap on testnet and assume testnet defaults for data-dir and the blockchain related parameters
-V, --version Prints version information
OPTIONS:
--change-address <bitcoin-change-address> The bitcoin address where any form of change or excess funds should be sent to
--receive-address <monero-receive-address> The monero address where you would like to receive monero
--seller <seller> The seller's address. Must include a peer ID part, i.e. `/p2p/`
--electrum-rpc <bitcoin-electrum-rpc-url> Provide the Bitcoin Electrum RPC URL
--bitcoin-target-block <bitcoin-target-block> Estimate Bitcoin fees such that transactions are confirmed within the specified number of blocks
--monero-daemon-address <monero-daemon-address> Specify to connect to a monero daemon of your choice: <host>:<port>
--tor-socks5-port <tor-socks5-port> Your local Tor socks5 proxy port [default: 9050]
```
This command has three core options:
- `--change-address`: A Bitcoin address you control. Will be used for refunds of any kind. You can also omit this flag which will refund any change to the internal wallet.
- `--receive-address`: A Monero address you control. This is where you will receive the Monero after the swap.
- `--seller`: The multiaddress of the seller you want to swap with.
## Discovering sellers
Running `swap list-sellers --help` gives us roughly the following output:
```
swap-list-sellers 0.8.0
Discover and list sellers (i.e. ASB providers)
USAGE:
swap list-sellers [FLAGS] [OPTIONS]
FLAGS:
-h, --help Prints help information
--testnet Swap on testnet and assume testnet defaults for data-dir and the blockchain related parameters
-V, --version Prints version information
OPTIONS:
--rendezvous-point <rendezvous-point> Address of the rendezvous point you want to use to discover ASBs
--tor-socks5-port <tor-socks5-port> Your local Tor socks5 proxy port [default: 9050]
```
Running `swap --testnet list-sellers --rendezvous-point /dns4/discover.unstoppableswap.net/tcp/8888/p2p/12D3KooWA6cnqJpVnreBVnoro8midDL9Lpzmg8oJPoAGi7YYaamE` will give you something like:
```
Connected to rendezvous point, discovering nodes in 'xmr-btc-swap-testnet' namespace ...
Discovered peer 12D3KooWPZ69DRp4wbGB3wJsxxsg1XW1EVZ2evtVwcARCF3a1nrx at /dns4/ac4hgzmsmekwekjbdl77brufqqbylddugzze4tel6qsnlympgmr46iid.onion/tcp/8765
+----------------+----------------+----------------+--------+----------------------------------------------------------------------------------------------------------------------------------------+
| PRICE | MIN_QUANTITY | MAX_QUANTITY | STATUS | ADDRESS |
+====================================================================================================================================================================================================+
| 0.00665754 BTC | 0.00010000 BTC | 0.00100000 BTC | Online | /dns4/ac4hgzmsmekwekjbdl77brufqqbylddugzze4tel6qsnlympgmr46iid.onion/tcp/8765/p2p/12D3KooWPZ69DRp4wbGB3wJsxxsg1XW1EVZ2evtVwcARCF3a1nrx |
+----------------+----------------+----------------+--------+----------------------------------------------------------------------------------------------------------------------------------------+
```
or this if a node is not reachable:
```
Connected to rendezvous point, discovering nodes in 'xmr-btc-swap-testnet' namespace ...
Discovered peer 12D3KooWPZ69DRp4wbGB3wJsxxsg1XW1EVZ2evtVwcARCF3a1nrx at /dns4/ac4hgzmsmekwekjbdl77brufqqbylddugzze4tel6qsnlympgmr46iid.onion/tcp/8765
+-------+--------------+--------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------+
| PRICE | MIN_QUANTITY | MAX_QUANTITY | STATUS | ADDRESS |
+============================================================================================================================================================================================+
| ??? | ??? | ??? | Unreachable | /dns4/ac4hgzmsmekwekjbdl77brufqqbylddugzze4tel6qsnlympgmr46iid.onion/tcp/8765/p2p/12D3KooWPZ69DRp4wbGB3wJsxxsg1XW1EVZ2evtVwcARCF3a1nrx |
+-------+--------------+--------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------+
```
## Automating discover and swapping
The `buy-xmr` and `list-sellers` command have been designed to be composed.
[This script](./discover_and_take.sh) is example of what can be done.
Deciding on the seller to use is non-trivial to automate which is why it is not implemented as part of the tool.
## Tor
By default, the CLI will look for Tor at the default socks port `9050` and automatically route all traffic with a seller through Tor.
This allows swapping with sellers that are only reachable with an onion address.
Disclaimer:
Communication with public blockchain explorers (Electrum, public XMR nodes) currently goes through clearnet.
For complete anonymity it is recommended to run your own blockchain nodes.
Use `swap buy-xmr --help` to see configuration options.

39
docs/cli/discover_and_take.sh
View file

@ -1,39 +0,0 @@
#!/bin/bash
# This is a utility script to showcase how the swap CLI can discover sellers and then trigger a swap using the discovered sellers
#
# 1st param: Path to the "swap" binary (aka the swap CLI)
# 2nd param: Multiaddress of the rendezvous node to be used for discovery
# 3rd param: Your Monero stagenet address where the XMR will be received
# 4th param: Your bech32 Bitcoin testnet address that will be used for any change output (e.g. refund scenario or when swapping an amount smaller than the transferred BTC)
#
# Example usage:
# discover_and_take.sh "PATH/TO/swap" "/dns4/discover.unstoppableswap.net/tcp/8888/p2p/12D3KooWA6cnqJpVnreBVnoro8midDL9Lpzmg8oJPoAGi7YYaamE" "YOUR_XMR_STAGENET_ADDRESS" "YOUR_BECH32_BITCOIN_TESTNET_ADDRESS"
CLI_PATH=$1
RENDEZVOUS_POINT=$2
YOUR_MONERO_ADDR=$3
YOUR_BITCOIN_ADDR=$4
CLI_LIST_SELLERS="$CLI_PATH --testnet --json --debug list-sellers --rendezvous-point $RENDEZVOUS_POINT"
echo "Requesting sellers with command: $CLI_LIST_SELLERS"
echo
BEST_SELLER=$($CLI_LIST_SELLERS | jq -s -c 'min_by(.status .Online .price)' | jq -r '.multiaddr, (.status .Online .price), (.status .Online .min_quantity), (.status .Online .max_quantity)')
read ADDR PRICE MIN MAX < <(echo $BEST_SELLER)
echo
echo "Seller with best price:"
echo " multiaddr : $ADDR"
echo " price : $PRICE sat"
echo " min_quantity: $MIN sat"
echo " max_quantity: $MAX sat"
echo
CLI_SWAP="$CLI_PATH --testnet --debug buy-xmr --receive-address $YOUR_MONERO_ADDR --change-address $YOUR_BITCOIN_ADDR --seller $ADDR"
echo "Starting swap with best seller using command $CLI_SWAP"
echo
$CLI_SWAP

55
docs/components/SwapProviderTable.tsx Normal file
View file

@ -0,0 +1,55 @@
import { useState, useEffect } from "react";
export default function SwapProviderTable() {
function satsToBtc(sats) {
return sats / 100000000;
}
async function getProviders() {
// from https://unstoppableswap.net/api/list with cors disabled
const response = await fetch("https://api.unstoppableswap.net/api/list");
const data = await response.json();
return data;
}
const [providers, setProviders] = useState([]);
useEffect(() => {
getProviders().then((data) => {
setProviders(data);
});
}, []);
return (
<div
style={{
overflowX: "scroll",
}}
>
<table>
<thead>
<tr>
<th>Multiaddress</th>
<th>Peer ID</th>
<th>Minimum Amount</th>
<th>Maximum Amount</th>
<th>Exchange Rate</th>
<th>Uptime</th>
</tr>
</thead>
<tbody>
{providers.map((provider) => (
<tr key={provider.peerId}>
<td>{provider.multiAddr}</td>
<td>{provider.peerId}</td>
<td>{satsToBtc(provider.minSwapAmount)} BTC</td>
<td>{satsToBtc(provider.maxSwapAmount)} BTC</td>
<td>{satsToBtc(provider.price)} XMR/BTC</td>
<td>{(provider.uptime * 100).toFixed(1)}%</td>
</tr>
))}
</tbody>
</table>
</div>
);
}

5
docs/next-env.d.ts vendored Normal file
View file

@ -0,0 +1,5 @@
/// <reference types="next" />
/// <reference types="next/image-types/global" />
// NOTE: This file should not be edited
// see https://nextjs.org/docs/basic-features/typescript for more information.

11
docs/next.config.js Normal file
View file

@ -0,0 +1,11 @@
const withNextra = require("nextra")({
theme: "nextra-theme-docs",
themeConfig: "./theme.config.jsx",
});
module.exports = withNextra({
output: "standalone",
});
// If you have other Next.js configurations, you can pass them as the parameter:
// module.exports = withNextra({ /* other next.js config */ })

23
docs/package.json Normal file
View file

@ -0,0 +1,23 @@
{
"name": "unstoppableswap-docs",
"version": "1.0.0",
"description": "Documentation for the UnstoppableSwap GUI",
"main": "index.js",
"license": "MIT",
"scripts": {
"dev": "next",
"build": "next build",
"start": "next start"
},
"dependencies": {
"next": "^14.2.4",
"nextra": "^2.13.4",
"nextra-theme-docs": "^2.13.4",
"react": "^18.3.1",
"react-dom": "^18.3.1"
},
"devDependencies": {
"@types/node": "20.14.5",
"typescript": "5.4.5"
}
}

7
docs/pages/_meta.json Normal file
View file

@ -0,0 +1,7 @@
{
"index": "Home",
"getting_started": "Getting Started",
"usage": "Usage",
"advanced": "Advanced",
"donate": "Donate"
}

3
docs/pages/advanced/_meta.json Normal file
View file

@ -0,0 +1,3 @@
{
"swap_on_testnet": "How to swap on Testnet"
}

49
docs/pages/advanced/swap_on_testnet.mdx Normal file
View file

@ -0,0 +1,49 @@
# Swapping on Testnet
Swapping on the testnet is a great way to test out the swap functionality without risking your mainnet assets. The testnet is a separate network from the mainnet, and the assets on the testnet are worthless.
To be exact, `testnet3` bitcoin will be swapped for `stagenet` Monero. You will need to set up two wallets to perform a swap:
- A Testnet3 Electrum Wallet (Bitcoin)
- A Stagenet Monero GUI Wallet
## Electrum
Download Electrum from the official [site](https://electrum.org/#download) and then start the wallet with the `--testnet` flag.
### Linux
```
./electrum --testnet
```
### Mac OS:
```
open -n /Applications/Electrum.app --args --testnet
```
### Windows:
If you install Electrum on Windows, you will have two programs you can start. One of them is called "Electrum Testnet".
### Getting testnet coins
To get some free Testnet coins visit a faucet like [this](https://testnet-faucet.mempool.co) one.
## Monero
If you use the `monero-wallet-cli` you simply need to start it with the `--stagenet` flag. If you use the GUI you can follow [this](https://www.youtube.com/watch?v=5E4aO3UAqJo) tutorial by the COMIT guys.
You can use this remote note:
```
stagenet.melo.tools:38081
```
## Installing the GUI
View the [Installation Instructions](../getting_started/install_instructions) if you haven't already installed the GUI.
## Making a swap
Start the GUI with the environment variable `TESTNET=true`. From here on you can follow the [Complete your first Atomic Swap](../usage/first_swap) guide with the difference that you will be using the testnet wallets. The process is the same, but you will be using the testnet wallets instead of the mainnet wallets.

13
docs/pages/donate.mdx Normal file
View file

@ -0,0 +1,13 @@
# Donate
We rely on generous donors like you to keep development moving forward. To bring Atomic Swaps to life, we need resources. If you have the possibility, please consider making a donation to the project. All funds will be used to support contributors and critical infrastructure.
If you interested in a partnership or want to support the project in a way that requires coordination with the contributors, contact [`@binarybaron:matrix.org`](https://matrix.to/#/@binarybaron:matrix.org) on Matrix.
```copy filename="Monero Donation Address"
49LEH26DJGuCyr8xzRAzWPUryzp7bpccC7Hie1DiwyfJEyUKvMFAethRLybDYrFdU1eHaMkKQpUPebY4WT3cSjEvThmpjPa
```
```copy filename="Bitcoin Donation Address"
bc1qz6lfs0r206396a9psunmkfpqh7sdf2zh3e7tnf
```

3
docs/pages/getting_started/_meta.json Normal file
View file

@ -0,0 +1,3 @@
{
"install_instructions": "Installation Instructions"
}

59
docs/pages/getting_started/install_instructions.mdx Normal file
View file

@ -0,0 +1,59 @@
# Installation Instructions
Precompiled binaries of the _GUI_ are available for download for:
- [Windows (64Bit)](#windows)
- [Mac OS (Silicon)](#mac-os-silicon)
- [Mac OS (Intel)](#mac-os-intel)
- [Linux (Debian/Ubuntu, amd64/x86_64)](#linux-debian)
- [Linux (Arch, x86_64)](#linux-pacman)
- [Linux (AppImage, x86_64)](#linux-appimage)
## Windows (64Bit) [#windows]
1. Download the latest release from GitHub [here](https://github.com/UnstoppableSwap/unstoppableswap-gui/releases/download/v0.6.0/UnstoppableSwap-Setup-0.6.0.exe)
2. Open the downloaded `.exe` installer
3. Follow the installation instructions
4. Open the `UnstoppableSwap` application from your Start menu
## Mac OS (Silicon / ARM / M1 / M2 / M3) [#mac-os-silicon]
1. Download the latest release from GitHub [here](https://github.com/UnstoppableSwap/unstoppableswap-gui/releases/download/v0.6.0/UnstoppableSwap-0.6.0-arm64.dmg)
2. Open the downloaded `.dmg` file
3. Drag the `UnstoppableSwap` icon to your Applications folder
4. Open the `UnstoppableSwap` application from your Applications folder
## Mac OS (Intel) [#mac-os-intel]
1. Download the latest release from GitHub [here](https://github.com/UnstoppableSwap/unstoppableswap-gui/releases/download/v0.6.0/UnstoppableSwap-0.6.0.dmg)
2. Open the downloaded `.dmg` file
3. Drag the `UnstoppableSwap` icon to your Applications folder
4. Open the `UnstoppableSwap` application from your Applications folder
## Linux (Debian/Ubuntu, amd64/x86_64) [#linux-debian]
For Debian-based distributions, you can download the Debian package and install it using `dpkg`.
```bash filename="install.sh"
wget https://github.com/UnstoppableSwap/unstoppableswap-gui/releases/download/v0.6.0/unstoppableswap-gui_0.6.0_amd64.deb
sudo dpkg -i unstoppableswap-gui_0.6.0_amd64.deb
```
## Linux (Pacman, Arch, x86_64) [#linux-pacman]
For Arch-based distributions, you can download the Pacman package and install it using `pacman`.
```bash filename="install.sh"
wget https://github.com/UnstoppableSwap/unstoppableswap-gui/releases/download/v0.6.0/unstoppableswap-gui-0.6.0.pacman
sudo pacman -U unstoppableswap-gui-0.6.0.pacman
```
## Linux (AppImage) [#linux-appimage]
For other Linux distributions, you can download the AppImage and run it directly. It includes all dependencies and will work on most systems.
```bash filename="install.sh"
wget https://github.com/UnstoppableSwap/unstoppableswap-gui/releases/download/v0.6.0/UnstoppableSwap-0.6.0.AppImage
chmod +x UnstoppableSwap-0.6.0.AppImage
./UnstoppableSwap-0.6.0.AppImage
```

1
docs/pages/index.mdx Normal file
View file

@ -0,0 +1 @@

5
docs/pages/usage/_meta.json Normal file
View file

@ -0,0 +1,5 @@
{
"first_swap": "Complete your first Atomic Swap",
"market_maker_discovery": "Swap Provider discovery",
"refund_punish": "Cancel, Refund and Punish explained"
}

117
docs/pages/usage/first_swap.mdx Normal file
View file

@ -0,0 +1,117 @@
# How to complete your first Atomic Swap
In this guide, we'll walk you through the process of completing your first atomic swap using the UnstoppableSwap GUI.
Although the process is quite intuitive, there are some nuances to be aware of, so we'll cover everything you need to know to get started.
## Prerequisites
To complete an Atomic Swap, you'll need to have the following:
1. A Monero wallet you can use to receive funds
2. A Bitcoin wallet you can use with some funds in it.
This wallet should also be able to generate a native SegWit address (an address starting with `bc1`).
This address will also receive any refunded Bitcoin if the swap is not completed.
3. _UnstoppableSwap GUI_ installed on your computer.
We'll refer to this as _GUI_ from now on. View the [installation instructions](../getting_started/install_instructions) if you haven't already installed the GUI.
import { Steps } from 'nextra/components'
## Performing the swap
<Steps>
### Choose a _Swap Provider_ to swap with
After opening the GUI, you'll be greeted with the main screen.
In the bottom of the screen you can see the currently selected _Swap Provider_.
This is who you'll send your Bitcoin to and who you'll receive the Monero from.
You can change the _Swap Provider_ by clicking on the arrow and selecting a different _Swap Provider_ from the list.
import { Callout } from 'nextra/components'
<Callout type="info">
Different _Swap Providers_ offer different exchange rates and differing amounts of liquidity. You may want to choose the _Swap Provider_ that best suits your needs.
</Callout>
You can also use input field to calculate the approximate amount of Monero you'll receive for a given amount of Bitcoin.
<Callout type="info">
The actual swap amount will be determined when you deposit your Bitcoin.
This is only used as a reference for you to get a rough idea of how much Monero you'll receive for your Bitcoin.
</Callout>
![image](/first_swap_1.png)
### Start the Swap
Once you've selected a _Swap Provider_, you can start the swap by clicking the `Swap` button.
This will open a new window where you need to enter two addresses:
1. the Monero address you want to receive the Monero to
2. the Bitcoin address where you want to receive the Bitcoin refund incase the swap is not completed successfully.
![image](/first_swap_2.png)
### Depositing Bitcoin
After pressing the <img src="/start_swap_button.png" style={{
height: "1lh",
display: "inline-block",
// center vertically
verticalAlign: "middle",
}}/> button, you'll be shown an offer by the _Swap Provider_. This includes:
- the exchange rate (how much Bitcoin they demand for 1 Monero)
- the minimum and maximum amounts you can swap
- the network fees that'll be spent on the Bitcoin lock transaction
<Callout type="info">
You can hover over these values to see their value in `USD`.
</Callout>
If you're happy with the offer, you can proceed by sending the Bitcoin to the address displayed on the screen.
All funds sent to this address will be used for the swap as long as they below the maximum amount.
<Callout type="info">
This is where the actual swap amount is determined.
Be careful to send only as much Bitcoin as you want to swap.
</Callout>
![image](/first_swap_3.png)
### Waiting for the swap to complete
After sending the Bitcoin, you'll need to wait a moment for the Bitcoin to be locked.
After the lock transaction has been confirmed, the other party will lock the Monero funds.
In most cases, it will take around 10 minutes for the Bitcoin lock transaction to be confirmed and 2 minutes later the Monero lock transaction will be confirmed.
![image](/first_swap_4.png)
The swap will go through four stages:
1. **Locking the Bitcoin**:
Your Bitcoin is locked in a 2-of-2 multisig address.
2. **_Swap Provider_ locks the Monero**:
The other party locks their Monero as well.
3. **_Swap Provider_ redeems _Bitcoin_**:
The other party redeems the Bitcoin.
4. **Redeeming the Monero**:
You redeem the Monero using a key that was revealed in step 3.
<table>
<tr>
<td>
![imgage](/first_swap_5.png)
</td>
<td>
![image](/first_swap_6.png)
</td>
<td>
![image](/first_swap_7.png)
</td>
</tr>
</table>
</Steps>

49
docs/pages/usage/market_maker_discovery.mdx Normal file
View file

@ -0,0 +1,49 @@
# _Swap Provider_ discovery
A _Swap Provider_ is a service run by a pseudonymous entity that offers to sell Monero in exchange for Bitcoin. To swap your Bitcoin for Monero you need to connect to a one of these _Swap Providers_.
The different ways to discover _Swap Providers_ are described below.
There are two ways to discover _Swap Providers_:
1. **Public Registry**: Community volunteers maintain a list of _Swap Providers_ that is provided to the GUI and is kept up to date automatically. This list is displayed in the GUI by default. The _Public Registry_ also stores additional information about the _Swap Providers_ such as their uptime and age, and makes it available to the GUI.
2. **Rendezvous**: The GUI can discover Swap Providers using the [_Rendezvous_ protocol](https://docs.libp2p.io/concepts/discovery-routing/rendezvous/). This protocol enables the GUI to find providers that register themselves at a _Rendezvous Point_. The GUI can query these points to get a list of registered providers. _Rendezvous Points_ are operated by community volunteers, and anyone can run one. The GUI can connect to various _Rendezvous Points_ to discover different _Swap Providers_.
## _Public Registry_
The providers from the registry are displayed in the GUI. If you want to connect to them directly without the GUI choose one from the table below.
import SwapProviderTable from "../../components/SwapProviderTable";
<div>
<SwapProviderTable />
</div>
## How to discover _Swap Providers_ via the _Rendezvous_ protocol
1. Open the _Swap Provider_ list by clicking the right-facing arrow in the widget on the _Swap_ tab.
<img src="/rendezvous_1.png" />
2. Click the <img src="/rendezvous_button_1.png" style={{
height: "1lh",
display: "inline-block",
// center vertically
verticalAlign: "middle",
}}/> button to open the _Discover swap providers_ dialog. Enter the _Multiaddress_ of the _Rendezvous Point_ you want to connect to. You can also choose one of the predined ones from the list below the Textfield. Click the _Connect_ button to connect to the rendezvous point.
<img src="/rendezvous_2.png" />
## How to add a _Swap Provider_ to the _Public Registry_
If you know of a _Swap Provider_ that is not yet in the _Public Registry_, you can submit it manually. Here's how you can do it:
1. Open the _Swap Provider_ list by clicking the right-facing arrow in the widget on the _Swap_ tab.
<img src="/rendezvous_1.png" />
2. Click the <img src="/public_registry_button_1.png" style={{
height: "1lh",
display: "inline-block",
// center vertically
verticalAlign: "middle",
}}/> button. Enter the _Multiaddress_ of the _Swap Provider_ as well as the _Peer ID_ of the provider. Click the _Submit_ button to submit the provider to the _Public Registry_.
<img src="/public_registry.png" />

22
docs/pages/usage/refund_punish.mdx Normal file
View file

@ -0,0 +1,22 @@
# Cancel, Refund, and Punish explained
Atomic Swaps offer a lot of security and privacy benefits, but they also come with some responsibilities. It is important to recognize that Atomic Swaps are trustless, but not risk-free. As long as you follow the rules of the protocol, you can be sure that you will not lose your funds.
If you want to learn more about technical details, you can read this paper: [Atomic Swaps between Bitcoin and Monero, _Philipp Hoenisch, Lucas Soriano del Pino_](https://arxiv.org/abs/2101.12332) or read this [blog post](https://comit.network/blog/2020/10/06/monero-bitcoin/).
## Cancel
If the _Swap Provider_ has not been able to redeem the Bitcoin within 12 hours (144 Bitcoin blocks) from the start of the swap, the swap will be cancelled.
This is done by either you or the _Swap Provider_ publishing a special Bitcoin transaction called the `Bitcoin Cancel Transaction`.
As soon as this transaction is included in the Bitcoin blockchain, the swap is locked in a state where only the [_Refund_](#refund) and [_Punish_](#punish) paths can be activated. The _Happy Path_ path where you redeem the Monero is no longer possible.
## Refund
As soon as the swap is cancelled, you can refund your Bitcoin. This is done by publishing the `Bitcoin Refund Transaction` on the Bitcoin blockchain.
If this is done within 12 hours (144 Bitcoin blocks) from the inclusion of the `Bitcoin Cancel Transaction`, you will get your Bitcoin back.
If you do not refund your Bitcoin within this time frame, the _Swap Provider_ can punish you. This is a security measure to ensure that you do not cancel the swap and then refuse to refund your Bitcoin which would result in the _Swap Provider_ losing their Monero.
## Punish
If you do not refund your Bitcoin within 12 hours (144 Bitcoin blocks) from the inclusion of the `Bitcoin Cancel Transaction`, the _Swap Provider_ will _punish_ you. This will result in the _Swap Provider_ taking your Bitcoin as a penalty for not refunding it in time.
Even if this state is reached and the _Swap Provider_ has punished you, there's still hope to redeem the Monero. The _Swap Provider_ can choose to allow you to redeem the Monero by transmitting a secret key to you. This however is at the discretion of the _Swap Provider_ and they are not obligated to do so.

BIN
docs/public/favicon.ico Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 15 KiB

114
docs/public/favicon.svg Normal file
View file

File diff suppressed because one or more lines are too long
Side by side

After

Width:  |  Height:  |  Size: 21 KiB

BIN
docs/public/first_swap_1.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 640 KiB

BIN
docs/public/first_swap_2.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 675 KiB

BIN
docs/public/first_swap_3.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 687 KiB

BIN
docs/public/first_swap_4.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 656 KiB

BIN
docs/public/first_swap_5.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 563 KiB

BIN
docs/public/first_swap_6.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 465 KiB

BIN
docs/public/first_swap_7.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 703 KiB

BIN
docs/public/public_registry.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 671 KiB

BIN
docs/public/public_registry_button_1.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 14 KiB

BIN
docs/public/rendezvous_1.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 712 KiB

BIN
docs/public/rendezvous_2.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 697 KiB

BIN
docs/public/rendezvous_button_1.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 24 KiB

BIN
docs/public/start_swap_button.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 34 KiB

8
docs/theme.config.jsx Normal file
View file

@ -0,0 +1,8 @@
export default {
logo: <span>UnstoppableSwap</span>,
project: {
link: "https://github.com/UnstoppableSwap/unstoppableswap-docs",
},
primaryHue: 14.3,
primarySaturation: 90.68,
};

18
docs/tsconfig.json Normal file
View file

@ -0,0 +1,18 @@
{
"compilerOptions": {
"lib": ["dom", "dom.iterable", "esnext"],
"allowJs": true,
"skipLibCheck": true,
"strict": false,
"noEmit": true,
"incremental": true,
"module": "esnext",
"esModuleInterop": true,
"moduleResolution": "node",
"resolveJsonModule": true,
"isolatedModules": true,
"jsx": "preserve"
},
"include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
"exclude": ["node_modules"]
}

2847
docs/yarn-error.log Normal file
View file

File diff suppressed because it is too large Load diff

2823
docs/yarn.lock Normal file
View file

File diff suppressed because it is too large Load diff