From 14527d36e3ff86b78d124c4cb36d12beaab68135 Mon Sep 17 00:00:00 2001 From: cryptoguard Date: Sat, 31 Jan 2026 11:47:35 -0500 Subject: [PATCH 1/4] Add Lightweight Modes guide with Electrum and Monero remote node docs --- .gitignore | 3 +- docs/about/under-the-hood.md | 2 +- docs/intro.md | 8 +- docs/user-guides/enable-disable-coins.md | 26 +- docs/user-guides/install.md | 70 +-- docs/user-guides/integrate-coin.md | 2 +- docs/user-guides/lightweight-modes.md | 534 +++++++++++++++++++++++ docs/user-guides/make-offer.md | 2 +- docs/user-guides/manage-enabled-coins.md | 12 +- docs/user-guides/market-making.md | 2 +- docs/user-guides/take-offer.md | 2 +- 11 files changed, 616 insertions(+), 47 deletions(-) create mode 100644 docs/user-guides/lightweight-modes.md diff --git a/.gitignore b/.gitignore index 280ca79..cfbefd0 100644 --- a/.gitignore +++ b/.gitignore @@ -20,4 +20,5 @@ yarn-debug.log* yarn-error.log* # Backups -docusaurus.config copy.js \ No newline at end of file +docusaurus.config copy.js +_reference/ diff --git a/docs/about/under-the-hood.md b/docs/about/under-the-hood.md index 40fe4e4..93df072 100644 --- a/docs/about/under-the-hood.md +++ b/docs/about/under-the-hood.md @@ -141,7 +141,7 @@ The SMSG network enables BasicSwap to offer functionality beyond what atomic swa * Automating complex swap procedures from the user's perspective * Facilitating secure communication between independent blockchain networks -In practice, BasicSwap functions as a decentralized alternative to SWIFT—providing a messaging protocol that enables direct peer-to-peer communication for executing atomic swaps using official coin cores (Bitcoin Core, Litecoin Core, etc.). +In practice, BasicSwap functions as a decentralized alternative to SWIFT in that it provides a messaging protocol that enables direct peer-to-peer communication for executing atomic swaps using official coin cores (Bitcoin Core, Litecoin Core, etc.) or [Electrum light wallets](/docs/user-guides/lightweight-modes) for supported coins (currently Bitcoin and Litecoin), or [remote nodes](/docs/user-guides/lightweight-modes#monero-remote-nodes) for Monero and Wownero. It's important to understand that BasicSwap itself does not process, initiate, or execute the actual swaps. Its role is strictly limited to enabling secure communication between trading parties and simplifying the complex process of performing atomic swaps across different blockchains. diff --git a/docs/intro.md b/docs/intro.md index b7444c4..9a05325 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -170,8 +170,8 @@ BasicSwap's primary function is to help users establish a secure communication c
    -
  • Bitcoin (BTC) - The original cryptocurrency
    • -
  • Litecoin (LTC) - Faster and cheaper Bitcoin alternative with privacy
    • +
  • Bitcoin (BTC) - The original cryptocurrency (supports light wallet mode)
    • +
  • Litecoin (LTC) - Faster and cheaper Bitcoin alternative with privacy (supports light wallet mode)
  • Bitcoin Cash (BCC) - Bitcoin fork focused on payments
  • Dogecoin (DOGE) - Bitcoin with dogs
  • Namecoin (NMC) - Decentralized DNS and public key infrastructure
    • @@ -179,8 +179,8 @@ BasicSwap's primary function is to help users establish a secure communication c
      -
    • Monero (XMR) - Leading privacy-focused cryptocurrency
      • -
    • Wownero (WOW) - Monero fork with experimental features
      • +
    • Monero (XMR) - Leading privacy-focused cryptocurrency (supports remote node mode)
      • +
    • Wownero (WOW) - Monero fork with experimental features (supports remote node mode)
    • Particl (PART) - Privacy coin with marketplace features
    • Firo (FIRO) - Privacy coin using zero-knowledge proofs
    • PIVX (PIVX) - Proof-of-stake privacy coin
      • diff --git a/docs/user-guides/enable-disable-coins.md b/docs/user-guides/enable-disable-coins.md index 11dd1d1..f459de5 100644 --- a/docs/user-guides/enable-disable-coins.md +++ b/docs/user-guides/enable-disable-coins.md @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 4 title: Enable or Disable Coins description: "How to enable or disable coins on your BasicSwap DEX instance" --- @@ -31,11 +31,18 @@ If you've built BasicSwap using the Docker method, follow these steps to enable ``` 2. Add a cryptocurrency to your BasicSwap instance by running the command below, replacing bitcoin with the specific coin you wish to enable after the `--addcoin` parameter. - + ```bash title="Terminal" docker-compose run --rm swapclient basicswap-prepare --datadir=/coindata --addcoin=bitcoin ``` + :::tip + When adding **Bitcoin** or **Litecoin**, you can enable [Electrum light wallet mode](/docs/user-guides/lightweight-modes) to avoid downloading their full blockchains. Add `--btc-mode=electrum` or `--ltc-mode=electrum` to the command: + ```bash title="Terminal" + docker-compose run --rm swapclient basicswap-prepare --datadir=/coindata --addcoin=bitcoin --btc-mode=electrum + ``` + ::: + :::tip You can copy an existing pruned datadir (excluding `bitcoin.conf` and any wallets) over to `$COINDATA_PATH/bitcoin`. Remove any existing wallets after copying over a pruned chain, or the Bitcoin daemon won't start. ::: @@ -74,14 +81,21 @@ Linux users can simplify the process of adding and removing coins with community 1. Stop BasicSwap completely. 2. Add a cryptocurrency to your BasicSwap instance by running the command below, replacing bitcoin with the specific coin you wish to enable after the `--addcoin` parameter. - - ```bash title="Terminal" + + ```bash title="Terminal" basicswap-prepare --usebtcfastsync --datadir=$SWAP_DATADIR --addcoin=bitcoin ``` + :::tip + When adding **Bitcoin** or **Litecoin**, you can enable [Electrum light wallet mode](/docs/user-guides/lightweight-modes) to avoid downloading their full blockchains. Add `--btc-mode=electrum` or `--ltc-mode=electrum` to the command: + ```bash title="Terminal" + basicswap-prepare --datadir=$SWAP_DATADIR --addcoin=bitcoin --btc-mode=electrum + ``` + ::: + 3. Apply the changes to your BasicSwap instance. - - ```bash title="Terminal" + + ```bash title="Terminal" . $SWAP_DATADIR/venv/bin/activate && python -V ``` diff --git a/docs/user-guides/install.md b/docs/user-guides/install.md index 54b24fc..5992233 100644 --- a/docs/user-guides/install.md +++ b/docs/user-guides/install.md @@ -58,7 +58,7 @@ Watch particularly for permission issues, dependency failures, or network connec ## Install Using Docker -BasicSwap is currently in beta stage and doesn't offer pre-compiled executables or integrations with third-party services (upcoming). You'll need to compile the source code and run a full node on your device. +BasicSwap is currently in beta stage and doesn't offer pre-compiled executables or integrations with third-party services (upcoming). You'll need to compile the source code and run a full node on your device for most coins. However, **Bitcoin and Litecoin** support an optional [Electrum light wallet mode](/docs/user-guides/lightweight-modes) that eliminates the need to sync their full blockchains, while **Monero** and **Wownero** support [remote node mode](/docs/user-guides/lightweight-modes#monero-remote-nodes) to avoid running a local daemon. ### Install Docker @@ -230,24 +230,28 @@ After creating BasicSwap's Docker image, it's time to configure it to your prefe 5. Determine whether you want to use fast synchronization for the Bitcoin blockchain by including the `--usebtcfastsync` parameter. Fast sync uses checkpoints to reduce initial setup time significantly. - 6. Append `--client-auth-password=` to the below command to optionally enable client authentication to protect your web UI and API port access from unauthorized access. + 6. **(Optional)** To use [Electrum light wallets](/docs/user-guides/lightweight-modes) instead of full nodes for Bitcoin and/or Litecoin, add the `--light` flag (enables Electrum for all supported coins) or use per-coin flags like `--btc-mode=electrum` or `--ltc-mode=electrum`. + + 7. **(Optional)** To use a [remote Monero node](/docs/user-guides/lightweight-modes#monero-remote-nodes) instead of running a local Monero daemon, prefix the command with `XMR_RPC_HOST` and `XMR_RPC_PORT` environment variables (e.g., `-e XMR_RPC_HOST="node2.monerodevs.org" -e XMR_RPC_PORT=18089`). + + 8. Append `--client-auth-password=` to the below command to optionally enable client authentication to protect your web UI and API port access from unauthorized access. + + 9. Execute the following command to configure your BasicSwap, adjusting it according to your preferences as described above. - 7. Execute the following command to configure your BasicSwap, adjusting it according to your preferences as described above. - ```bash title="Terminal" docker run --rm -t --name swap_prepare -v $COINDATA_PATH:/coindata i_swapclient basicswap-prepare --datadir=/coindata --withcoins=monero,bitcoin --htmlhost="0.0.0.0" --wshost="0.0.0.0" --xmrrestoreheight=$CURRENT_XMR_HEIGHT --usebtcfastsync ``` - 8. Note down and store the mnemonic provided by the above command in a safe place. It serves as your backup key and is valid for all enabled coins. + 10. Note down and store the mnemonic provided by the above command in a safe place. It serves as your backup key and is valid for all enabled coins. + + 11. Note down the result of the following command, it will speed up the process of recovering your Monero if needed. - 9. Note down the result of the following command, it will speed up the process of recovering your Monero if needed. - ```bash title="Terminal" echo $CURRENT_XMR_HEIGHT ``` - 10. **(Optional)** Adjust your timezone by specifying the appropriate `TZ` value in your `.env` file, located within the BasicSwap Docker directory. Use the `timedatectl list-timezones` command to view valid timezone options. - + 12. **(Optional)** Adjust your timezone by specifying the appropriate `TZ` value in your `.env` file, located within the BasicSwap Docker directory. Use the `timedatectl list-timezones` command to view valid timezone options. + ```bash title="Terminal" nano .env ``` @@ -256,15 +260,15 @@ After creating BasicSwap's Docker image, it's time to configure it to your prefe 1. Open a terminal. - + 2. Navigate to BasicSwap's Docker folder. - + ```bash title="Terminal" cd basicswap/docker/ ``` 3. Set `xmrrestoreheight` to Monero's current chain height. - + ```bash title="Terminal" CURRENT_XMR_HEIGHT=$(curl -s http://node2.monerodevs.org:18089/get_info | jq .height) ``` @@ -273,23 +277,27 @@ After creating BasicSwap's Docker image, it's time to configure it to your prefe 5. Determine whether you want to use fast synchronization for the Bitcoin blockchain by including the `--usebtcfastsync` parameter. Fast sync uses checkpoints to reduce initial setup time significantly. - 6. Append `--client-auth-password=` to the below command to optionally enable client authentication to protect your web UI and API port access from unauthorized access. + 6. **(Optional)** To use [Electrum light wallets](/docs/user-guides/lightweight-modes) instead of full nodes for Bitcoin and/or Litecoin, add the `--light` flag (enables Electrum for all supported coins) or use per-coin flags like `--btc-mode=electrum` or `--ltc-mode=electrum`. + + 7. **(Optional)** To use a [remote Monero node](/docs/user-guides/lightweight-modes#monero-remote-nodes) instead of running a local Monero daemon, prefix the command with `XMR_RPC_HOST` and `XMR_RPC_PORT` environment variables (e.g., `-e XMR_RPC_HOST="node2.monerodevs.org" -e XMR_RPC_PORT=18089`). + + 8. Append `--client-auth-password=` to the below command to optionally enable client authentication to protect your web UI and API port access from unauthorized access. + + 9. Execute the following command to configure your BasicSwap, adjusting it according to your preferences as described above. - 7. Execute the following command to configure your BasicSwap, adjusting it according to your preferences as described above. - ```bash title="Terminal" docker run --rm -t --name swap_prepare -v $COINDATA_PATH:/coindata i_swapclient basicswap-prepare --datadir=/coindata --withcoins=monero,bitcoin --htmlhost="0.0.0.0" --wshost="0.0.0.0" --xmrrestoreheight=$CURRENT_XMR_HEIGHT --usebtcfastsync ``` - 8. Note down and store the mnemonic provided by the above command in a safe place. It serves as your backup key and is valid for all enabled coins. + 10. Note down and store the mnemonic provided by the above command in a safe place. It serves as your backup key and is valid for all enabled coins. + + 11. Note down the result of the following command, it will speed up the process of recovering your Monero if needed. - 9. Note down the result of the following command, it will speed up the process of recovering your Monero if needed. - ```bash title="Terminal" echo $CURRENT_XMR_HEIGHT ``` - 10. **(Optional)** Adjust your timezone by specifying the appropriate `TZ` value in your `.env` file, located within the BasicSwap Docker directory. Use the `timedatectl list-timezones` command to view valid timezone options. + 12. **(Optional)** Adjust your timezone by specifying the appropriate `TZ` value in your `.env` file, located within the BasicSwap Docker directory. Use the `timedatectl list-timezones` command to view valid timezone options. ```bash title="Terminal" nano .env @@ -446,10 +454,14 @@ Once the installation is complete, configure BasicSwap according to your require 5. Determine whether you want to use fast synchronization for the Bitcoin blockchain by including the `--usebtcfastsync` parameter. Fast sync uses checkpoints to reduce initial setup time significantly. - 6. Append `--client-auth-password=` to the below command to optionally enable client authentication to protect your web UI and API port access from unauthorized access. + 6. **(Optional)** To use [Electrum light wallets](/docs/user-guides/lightweight-modes) instead of full nodes for Bitcoin and/or Litecoin, add the `--light` flag (enables Electrum for all supported coins) or use per-coin flags like `--btc-mode=electrum` or `--ltc-mode=electrum`. + + 7. **(Optional)** To use a [remote Monero node](/docs/user-guides/lightweight-modes#monero-remote-nodes) instead of running a local Monero daemon, prefix the command with `XMR_RPC_HOST` and `XMR_RPC_PORT` environment variables (e.g., `XMR_RPC_HOST="node2.monerodevs.org" XMR_RPC_PORT=18089`). + + 8. Append `--client-auth-password=` to the below command to optionally enable client authentication to protect your web UI and API port access from unauthorized access. + + 9. Execute the following command to configure your BasicSwap, adjusting it according to your preferences as described above. - 7. Execute the following command to configure your BasicSwap, adjusting it according to your preferences as described above. - ```bash title="Terminal" basicswap-prepare --datadir=$SWAP_DATADIR --withcoins=monero,bitcoin --xmrrestoreheight=$CURRENT_XMR_HEIGHT --usebtcfastsync ``` @@ -458,13 +470,13 @@ Once the installation is complete, configure BasicSwap according to your require 1. Open a terminal. 2. Navigate to your BasicSwap folder. - + ```bash title="Terminal" cd $HOME/coinswaps ``` 3. Set `xmrrestoreheight` to Monero's current chain height. - + ```bash title="Terminal" CURRENT_XMR_HEIGHT=$(curl -s http://node2.monerodevs.org:18089/get_info | jq .height) ``` @@ -473,10 +485,14 @@ Once the installation is complete, configure BasicSwap according to your require 5. Determine whether you want to use fast synchronization for the Bitcoin blockchain by including the `--usebtcfastsync` parameter. Fast sync uses checkpoints to reduce initial setup time significantly. - 6. Append `--client-auth-password=` to the below command to optionally enable client authentication to protect your web UI and API port access from unauthorized access. + 6. **(Optional)** To use [Electrum light wallets](/docs/user-guides/lightweight-modes) instead of full nodes for Bitcoin and/or Litecoin, add the `--light` flag (enables Electrum for all supported coins) or use per-coin flags like `--btc-mode=electrum` or `--ltc-mode=electrum`. + + 7. **(Optional)** To use a [remote Monero node](/docs/user-guides/lightweight-modes#monero-remote-nodes) instead of running a local Monero daemon, prefix the command with `XMR_RPC_HOST` and `XMR_RPC_PORT` environment variables (e.g., `XMR_RPC_HOST="node2.monerodevs.org" XMR_RPC_PORT=18089`). + + 8. Append `--client-auth-password=` to the below command to optionally enable client authentication to protect your web UI and API port access from unauthorized access. + + 9. Execute the following command to configure your BasicSwap, adjusting it according to your preferences as described above. - 7. Execute the following command to configure your BasicSwap, adjusting it according to your preferences as described above. - ```bash title="Terminal" basicswap-prepare --datadir=$SWAP_DATADIR --withcoins=monero,bitcoin --xmrrestoreheight=$CURRENT_XMR_HEIGHT --usebtcfastsync ``` diff --git a/docs/user-guides/integrate-coin.md b/docs/user-guides/integrate-coin.md index 2bfcf5a..a36d350 100644 --- a/docs/user-guides/integrate-coin.md +++ b/docs/user-guides/integrate-coin.md @@ -1,5 +1,5 @@ --- -sidebar_position: 8 +sidebar_position: 9 title: Integrate a Coin description: "How to add your coin to the BasicSwap DEX" --- diff --git a/docs/user-guides/lightweight-modes.md b/docs/user-guides/lightweight-modes.md new file mode 100644 index 0000000..5e21391 --- /dev/null +++ b/docs/user-guides/lightweight-modes.md @@ -0,0 +1,534 @@ +--- +sidebar_position: 3 +title: Lightweight Modes +description: "How to use Electrum light wallets and Monero remote nodes on BasicSwap DEX instead of running full nodes" +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import React from 'react'; + +# Lightweight Modes + +BasicSwap supports lightweight alternatives to running full blockchain nodes for select coins. Instead of downloading and syncing entire blockchains, you can use **Electrum light wallets** for Bitcoin and Litecoin, or connect to a **remote Monero node** for Monero and Wownero. These modes let you start trading much faster with significantly lower disk and bandwidth requirements. + +:::info +Lightweight modes are currently available for **Bitcoin**, **Litecoin** (via Electrum), and **Monero**, **Wownero** (via remote nodes). All other coins still require full nodes. +::: + +## Electrum Light Wallets (Bitcoin & Litecoin) + +BasicSwap supports **Electrum light wallets** as an alternative to running full blockchain nodes for **Bitcoin (BTC)** and **Litecoin (LTC)**. Instead of downloading and syncing an entire blockchain, Electrum mode connects to remote ElectrumX servers to query blockchain data. + +### How It Works + +In standard (RPC) mode, BasicSwap runs a full node for each enabled coin, which means downloading the entire blockchain and verifying every transaction locally. This provides maximum security and trustlessness but requires significant disk space and sync time. + +In **Electrum mode**, BasicSwap connects to remote ElectrumX servers using the standardized ElectrumX protocol. These servers index the blockchain and respond to balance, transaction, and UTXO queries on your behalf. Your wallet keys remain local, with only public address information being sent to the server. + +### Trade-offs + +| | Full Node (RPC) | Electrum Light Wallet | +|---|---|---| +| **Blockchain download** | Full chain required | None | +| **Disk space** | Significant (potentially hundreds of GB for BTC) | Minimal | +| **Setup time** | Hours to days (initial sync) | Seconds | +| **Trust model** | Fully trustless; you verify everything | Trusts the Electrum server to provide accurate data | +| **Privacy** | Maximum; no third party sees your queries | Server can see which addresses you query | +| **Availability** | Independent; your own node | Depends on server availability (auto-failover built in) | + +### Supported Coins + +Only the following coins currently support Electrum mode: + +- **Bitcoin (BTC)** +- **Litecoin (LTC)** + +### Enable Electrum Mode + +There are multiple ways to enable Electrum light wallet mode, depending on whether you are setting up BasicSwap for the first time or modifying an existing installation. + +#### During Initial Setup + +You can enable Electrum mode when first configuring BasicSwap by adding the `--light` flag to the `basicswap-prepare` command. This enables Electrum for all supported coins (BTC and LTC). + + + + ```bash title="Terminal" + docker run --rm -t --name swap_prepare -v $COINDATA_PATH:/coindata i_swapclient basicswap-prepare --datadir=/coindata --withcoins=monero,bitcoin --htmlhost="0.0.0.0" --wshost="0.0.0.0" --xmrrestoreheight=$CURRENT_XMR_HEIGHT --light + ``` + + + ```bash title="Terminal" + basicswap-prepare --datadir=$SWAP_DATADIR --withcoins=monero,bitcoin --xmrrestoreheight=$CURRENT_XMR_HEIGHT --light + ``` + + + +To enable Electrum for a specific coin only, use the per-coin mode flags instead: + + + + ```bash title="Terminal" + docker run --rm -t --name swap_prepare -v $COINDATA_PATH:/coindata i_swapclient basicswap-prepare --datadir=/coindata --withcoins=monero,bitcoin,litecoin --htmlhost="0.0.0.0" --wshost="0.0.0.0" --xmrrestoreheight=$CURRENT_XMR_HEIGHT --btc-mode=electrum --ltc-mode=electrum + ``` + + + ```bash title="Terminal" + basicswap-prepare --datadir=$SWAP_DATADIR --withcoins=monero,bitcoin,litecoin --xmrrestoreheight=$CURRENT_XMR_HEIGHT --btc-mode=electrum --ltc-mode=electrum + ``` + + + +You can also specify a custom Electrum server during setup: + +```bash title="Terminal" +basicswap-prepare --datadir=$SWAP_DATADIR --withcoins=bitcoin --btc-mode=electrum --btc-electrum-server=custom.server.com:50002:true +``` + +The server format is `host:port[:ssl]`, where `ssl` is `true` (default) or `false`. + +#### Via the Web UI + +You can switch an existing coin to Electrum mode through the BasicSwap Settings page: + +1. Navigate to **Settings** in the BasicSwap web interface. +2. Locate the coin you want to switch (Bitcoin or Litecoin). +3. Change the **Connection Type** dropdown from `rpc` to `electrum`. +4. (Optional) Configure custom Electrum servers in the server list fields. +5. (Optional) Toggle **Auto-transfer on mode switch** (enabled by default). +6. (Optional) Adjust the **Address Gap Limit** (default: 20). +7. Click **Apply** to save changes. + +:::warning +You cannot switch connection modes while the coin has active swaps in progress. Complete or cancel all pending swaps before switching. +::: + +#### Via Configuration File + +You can manually edit the `basicswap_settings.json` file to enable Electrum mode: + +1. Stop BasicSwap. +2. Open `basicswap_settings.json` in a text editor (located in your data directory). +3. Under the coin's `chainclients` section, set the following: + +```json title="basicswap_settings.json" +{ + "chainclients": { + "bitcoin": { + "connection_type": "electrum", + "manage_daemon": false + } + } +} +``` + +4. Restart BasicSwap. + +### Switching Between Modes + +You can switch between full node (RPC) and Electrum mode at any time, provided there are no active swaps for that coin. + +#### Automatic Fund Transfer + +By default, **auto-transfer on mode switch** is enabled. When you switch modes, BasicSwap will automatically sweep your funds from the old wallet to the new one: + +- **RPC → Electrum:** Funds are swept from your full node wallet to Electrum-derived addresses. +- **Electrum → RPC:** Funds are swept from Electrum addresses back to your full node wallet. + +A standard network fee is deducted from the sweep transaction. + +#### Manual Fund Transfer + +If you disable auto-transfer (`auto_transfer_on_mode_switch: false`), you must manually move your funds between wallets when switching modes. + +:::warning +When auto-transfer is disabled, your old wallet's funds will **not** be accessible from the new mode until you manually transfer them. Make sure to move your funds before or after switching, or enable auto-transfer to have this handled automatically. +::: + +### Custom Electrum Servers + +BasicSwap ships with a set of default Electrum servers for each supported coin. You can configure custom servers for additional control or privacy. + +#### Default Servers + + + + | Server | Port | SSL | + |--------|------|-----| + | bitcoin.stackwallet.com | 50002 | Yes | + | electrum.blockstream.info | 50002 | Yes | + | electrum.emzy.de | 50002 | Yes | + | electrum.bitaroo.net | 50002 | Yes | + | electrum.acinq.co | 50002 | Yes | + | btc.lastingcoin.net | 50002 | Yes | + + + | Server | Port | SSL | + |--------|------|-----| + | litecoin.stackwallet.com | 20063 | Yes | + | electrum-ltc.bysh.me | 50002 | Yes | + | electrum.ltc.xurious.com | 50002 | Yes | + | backup.electrum-ltc.org | 443 | Yes | + | ltc.rentonisk.com | 50002 | Yes | + | electrum-ltc.petrkr.net | 60002 | Yes | + | electrum.jochen-hoenicke.de | 50004 | Yes | + + + +#### Server Format + +Servers are specified in `host:port:ssl` format: + +- `bitcoin.stackwallet.com:50002:true`; SSL enabled (default) +- `my-server.local:50001:false`; SSL disabled + +#### Configuring Custom Servers + +**Via the Web UI:** Navigate to Settings, select the coin, and enter your servers in the clearnet or onion server text fields (one per line). + +**Via configuration file:** Add the `electrum_clearnet_servers` and/or `electrum_onion_servers` lists to the coin's section in `basicswap_settings.json`: + +```json title="basicswap_settings.json" +{ + "chainclients": { + "bitcoin": { + "connection_type": "electrum", + "manage_daemon": false, + "electrum_clearnet_servers": [ + "bitcoin.stackwallet.com:50002:true", + "electrum.blockstream.info:50002:true" + ], + "electrum_onion_servers": [ + "your-onion-server.onion:50001:false" + ] + } + } +} +``` + +### Tor Integration + +Electrum mode fully supports Tor for enhanced privacy. + +When Tor is enabled on your BasicSwap instance: + +1. **Onion servers are prioritized:** if you have `.onion` Electrum servers configured, they will be used first. +2. **Clearnet servers are routed through Tor:** if no onion servers are available, clearnet servers are accessed through a SOCKS5 Tor proxy. +3. **SSL is automatically disabled over Tor:** Tor already provides end-to-end encryption, so the additional SSL layer is unnecessary. + +No additional configuration is needed beyond enabling Tor on your BasicSwap instance and optionally adding `.onion` servers to your Electrum server list. + +### Monitoring Electrum Wallets + +When a coin is running in Electrum mode, the **Wallets** page in the BasicSwap web interface displays different information than in full node mode: + +- **Connected Server:** the hostname and port of the currently connected Electrum server. +- **Server Version:** the version of the ElectrumX server. +- **Connection Status:** one of the following: + - `connected`: successfully connected and operational. + - `disconnected`: temporarily disconnected; BasicSwap will automatically attempt reconnection. + - `all_failed`: all configured servers have failed. Check your server list and network connectivity. + +Unlike full node mode, there is no blockchain sync progress bar. Electrum wallets are ready as soon as a server connection is established. + +#### Server Health & Failover + +BasicSwap automatically monitors server health and handles failover: + +- Servers are pinged at regular intervals to detect failures. +- If a server becomes unresponsive, BasicSwap automatically switches to another available server. +- Rate-limited servers are temporarily blacklisted (5 minute backoff). +- Server performance is tracked to prioritize faster, more reliable servers. + +### Electrum Configuration Reference + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `connection_type` | string | `"rpc"` | Set to `"electrum"` to enable light wallet mode | +| `manage_daemon` | bool | `true` | Must be `false` when using Electrum mode | +| `electrum_clearnet_servers` | list | (built-in defaults) | Custom clearnet servers in `host:port:ssl` format | +| `electrum_onion_servers` | list | `[]` | Custom `.onion` servers for Tor | +| `electrum_poll_interval` | int | `10` | Polling interval in seconds for wallet updates | +| `auto_transfer_on_mode_switch` | bool | `true` | Automatically sweep funds when switching between RPC and Electrum | +| `address_gap_limit` | int | `20` | BIP44 gap limit for address derivation and discovery | + +### Electrum Limitations + +- **Supported coins:** Only Bitcoin and Litecoin. All other coins require full nodes. +- **Trust model:** Electrum mode trusts the remote server to provide accurate blockchain data. For maximum trustlessness, use full node (RPC) mode. +- **Litecoin MWEB:** MWEB addresses (starting with `ltcmweb1`) are not supported in Electrum mode. Use standard Litecoin addresses. +- **Server availability:** If all configured servers are down, wallet operations will be unavailable until a server becomes reachable. Built-in failover minimizes this risk. + +--- + +## Monero Remote Nodes + +BasicSwap supports connecting to a **remote Monero daemon** instead of running a local `monerod` instance. This avoids downloading the full Monero blockchain while still keeping your wallet running locally. The same mechanism also applies to **Wownero**. + +:::info +With remote node mode, only the daemon (`monerod`) is remote. The wallet (`monero-wallet-rpc`) always runs locally on your machine. Your keys never leave your device. +::: + +### How It Works + +In standard mode, BasicSwap runs both a local Monero daemon (`monerod`) and a local wallet RPC (`monero-wallet-rpc`). The daemon downloads and validates the entire Monero blockchain, which requires significant disk space and sync time. + +In **remote node mode**, BasicSwap skips running a local daemon and instead connects `monero-wallet-rpc` to an external Monero daemon. The wallet generates and manages keys locally, and only communicates with the remote daemon to query blockchain data and broadcast transactions. + +### Trade-offs + +| | Full Node (Local Daemon) | Remote Node | +|---|---|---| +| **Blockchain download** | Full chain required (~200+ GB) | None | +| **Disk space** | Significant | Minimal (wallet data only) | +| **Setup time** | Hours to days (initial sync) | Seconds | +| **Trust model** | Fully trustless; you verify everything | Trusts the remote daemon to provide accurate data | +| **Privacy** | Maximum; no third party sees your queries | Remote node can see your transaction queries | +| **Availability** | Independent; your own node | Depends on remote node availability | + +### Enable Remote Node Mode + +There are multiple ways to enable remote node mode, depending on whether you are setting up BasicSwap for the first time or modifying an existing installation. + +#### During Initial Setup + +You can configure BasicSwap to use a remote Monero node during initial setup by setting the `XMR_RPC_HOST` and `XMR_RPC_PORT` environment variables before running `basicswap-prepare`. This automatically sets `manage_daemon` to `false` for Monero. + + + + ```bash title="Terminal" + docker-compose run --rm -e XMR_RPC_HOST="node2.monerodevs.org" -e XMR_RPC_PORT=18089 swapclient basicswap-prepare --datadir=/coindata --withcoins=monero,bitcoin --htmlhost="0.0.0.0" --wshost="0.0.0.0" --xmrrestoreheight=$CURRENT_XMR_HEIGHT + ``` + + + ```bash title="Terminal" + XMR_RPC_HOST="node2.monerodevs.org" XMR_RPC_PORT=18089 basicswap-prepare --datadir=$SWAP_DATADIR --withcoins=monero,bitcoin --xmrrestoreheight=$CURRENT_XMR_HEIGHT + ``` + + + +If the remote node requires authentication, also set `XMR_RPC_USER` and `XMR_RPC_PWD`: + + + + ```bash title="Terminal" + docker-compose run --rm -e XMR_RPC_HOST="192.168.1.9" -e XMR_RPC_PORT=18089 -e XMR_RPC_USER="myuser" -e XMR_RPC_PWD="mypassword" swapclient basicswap-prepare --datadir=/coindata --withcoins=monero,bitcoin --htmlhost="0.0.0.0" --wshost="0.0.0.0" --xmrrestoreheight=$CURRENT_XMR_HEIGHT + ``` + + + ```bash title="Terminal" + XMR_RPC_HOST="192.168.1.9" XMR_RPC_PORT=18089 XMR_RPC_USER="myuser" XMR_RPC_PWD="mypassword" basicswap-prepare --datadir=$SWAP_DATADIR --withcoins=monero,bitcoin --xmrrestoreheight=$CURRENT_XMR_HEIGHT + ``` + + + +#### Via the Web UI + +You can switch to a remote Monero node through the BasicSwap Settings page: + +1. Navigate to **Settings** in the BasicSwap web interface. +2. Expand the **Monero** card. +3. Set **Manage Daemon** to `False`. +4. Enter the remote node's IP or hostname in **Daemon RPC Host**. +5. Enter the remote node's port in **Daemon RPC Port** (typically `18081` or `18089`). +6. (Optional) Enable **Automatically Select Daemon** and add multiple nodes to the **Trusted Public Nodes** list for automatic failover. +7. (Optional) Set **Transaction Fee Priority** (Auto, Slow, Normal, or Fast). +8. Click **Apply** to save changes. + +#### Via Configuration File + +You can manually edit the `basicswap.json` file to enable remote node mode: + +1. Stop BasicSwap. +2. Open `basicswap.json` in a text editor (located in your data directory). +3. Under `chainclients.monero`, set the following: + +```json title="basicswap.json" +{ + "chainclients": { + "monero": { + "connection_type": "rpc", + "manage_daemon": false, + "manage_wallet_daemon": true, + "rpchost": "node2.monerodevs.org", + "rpcport": 18089 + } + } +} +``` + +4. Restart BasicSwap. + +For authenticated nodes, also add `rpcuser` and `rpcpassword`: + +```json title="basicswap.json" +{ + "chainclients": { + "monero": { + "connection_type": "rpc", + "manage_daemon": false, + "manage_wallet_daemon": true, + "rpchost": "192.168.1.9", + "rpcport": 18089, + "rpcuser": "myuser", + "rpcpassword": "mypassword" + } + } +} +``` + +### Private Remote Nodes + +If you run your own Monero node on a separate machine (e.g., a home server or VPS), you can connect BasicSwap to it either directly or through an SSH tunnel. + +#### Without SSH Tunneling + +1. Configure `monerod.conf` on the remote machine: + +```ini title="monerod.conf" +rpc-login=myuser:mypassword +rpc-restricted-bind-port=18089 +rpc-restricted-bind-ip=0.0.0.0 +``` + +2. Open port `18089` in the remote machine's firewall if necessary. + +3. Set the following in your BasicSwap `basicswap.json`: + +```json title="basicswap.json" +{ + "chainclients": { + "monero": { + "connection_type": "rpc", + "manage_daemon": false, + "manage_wallet_daemon": true, + "rpchost": "192.168.1.9", + "rpcport": 18089, + "rpcuser": "myuser", + "rpcpassword": "mypassword" + } + } +} +``` + +4. Verify the connection from your BasicSwap machine: + +```bash title="Terminal" +curl http://192.168.1.9:18089/json_rpc -u myuser:mypassword --digest -d '{"jsonrpc":"2.0","id":"0","method":"get_info"}' -H 'Content-Type: application/json' +``` + +#### With SSH Tunneling + +SSH tunneling provides a secure connection without exposing RPC ports to the network. No RPC authentication is needed since SSH handles security. + +1. On the remote Monero node, configure `monerod.conf`: + +```ini title="monerod.conf" +rpc-restricted-bind-port=18089 +``` + +2. Create an SSH tunnel from your BasicSwap machine to the remote node: + +```bash title="Terminal" +ssh -N -L 18089:localhost:18089 user@REMOTE_NODE_IP +``` + +Or, from the remote machine, create a reverse tunnel to your BasicSwap machine: + +```bash title="Terminal" +ssh -N -R 18089:localhost:18089 user@LOCAL_BSX_IP +``` + +3. Set the following in your BasicSwap `basicswap.json`: + +```json title="basicswap.json" +{ + "chainclients": { + "monero": { + "connection_type": "rpc", + "manage_daemon": false, + "manage_wallet_daemon": true, + "rpchost": "localhost", + "rpcport": 18089 + } + } +} +``` + +### Trusted vs Untrusted Daemon + +BasicSwap automatically determines whether to treat the remote daemon as trusted or untrusted based on the daemon's IP address: + +- **Trusted (private IPs):** `127.x.x.x`, `10.x.x.x`, `172.16-31.x.x`, `192.168.x.x`, `localhost`, and `*.local` addresses are treated as trusted. The wallet skips some verification steps for better performance. +- **Untrusted (public IPs):** All other addresses are treated as untrusted. The wallet performs additional verification to guard against a potentially dishonest daemon. + +You can override the auto-detection: + +- **During setup:** Add `--trustremotenode` to the `basicswap-prepare` command. +- **In configuration:** Set `"trusted_daemon": true` or `"trusted_daemon": false` in the Monero section of `basicswap.json`. + +:::warning +Only mark a daemon as trusted if you fully control it. A malicious trusted daemon could provide false blockchain data to your wallet. +::: + +### Automatic Daemon Selection + +BasicSwap can automatically select from a list of remote Monero daemons, providing failover if one becomes unavailable. + +To enable automatic daemon selection: + +1. Set `"automatically_select_daemon": true` in `basicswap.json` or enable it via the Settings UI. +2. Add remote node URLs to the `"remote_daemon_urls"` list in configuration, or the **Trusted Public Nodes** field in the Settings UI. + +```json title="basicswap.json" +{ + "chainclients": { + "monero": { + "connection_type": "rpc", + "manage_daemon": false, + "manage_wallet_daemon": true, + "automatically_select_daemon": true, + "remote_daemon_urls": [ + "node2.monerodevs.org:18089", + "node.xmr.to:18081" + ] + } + } +} +``` + +BasicSwap tries the last-used node first. If it fails, the list is shuffled and each node is tried in turn. The first successful connection becomes the new default. + +### Tor Integration + +When Tor is enabled on your BasicSwap instance, remote Monero daemon connections are automatically routed through a SOCKS5 Tor proxy, unless the daemon is on a private IP address (which would be unnecessary and counterproductive). + +No additional configuration is needed beyond enabling Tor on your BasicSwap instance. + +### Monero Configuration Reference + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `manage_daemon` | bool | `true` | Set to `false` for remote node mode | +| `manage_wallet_daemon` | bool | `true` | Wallet always runs locally; leave as `true` | +| `rpchost` | string | `"127.0.0.1"` | Remote daemon IP or hostname | +| `rpcport` | int | `29798` | Remote daemon RPC port (public nodes typically use `18081` or `18089`) | +| `rpcuser` | string | `""` | Optional RPC authentication username | +| `rpcpassword` | string | `""` | Optional RPC authentication password | +| `trusted_daemon` | string | `"auto"` | `true`, `false`, or `"auto"` (auto-detects based on IP) | +| `automatically_select_daemon` | bool | `false` | Enable automatic daemon selection from URL list | +| `remote_daemon_urls` | list | `[]` | List of `host:port` strings for daemon failover | +| `fee_priority` | int | `0` | Transaction fee priority: 0=auto, 1=slow, 2=normal, 3=fast | +| `rpctimeout` | int | `60` | RPC timeout in seconds | + +### Monero Limitations + +- **Trust model:** Remote node mode trusts the remote daemon for blockchain data accuracy. For maximum trustlessness, run your own local Monero node. +- **Public node reliability:** Public Monero nodes may be unreliable, rate-limited, or slow. Consider running your own remote node or using automatic daemon selection with multiple nodes for better reliability. +- **Privacy:** The remote node can see which transactions you broadcast and which outputs you query. For maximum privacy, run your own node. +- **Wallet still runs locally:** `monero-wallet-rpc` runs on your machine and requires some system resources, though significantly less than a full daemon. + +:::tip +All Monero remote node options also apply to **Wownero**. Use the `WOW_` environment variable prefix (e.g., `WOW_RPC_HOST`, `WOW_RPC_PORT`) during setup, and configure the `wownero` section in `basicswap.json` the same way as `monero`. +::: diff --git a/docs/user-guides/make-offer.md b/docs/user-guides/make-offer.md index 3c8d988..dd9ed34 100644 --- a/docs/user-guides/make-offer.md +++ b/docs/user-guides/make-offer.md @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 6 title: Make an Offer description: "How to make and manage trading offers on BasicSwap DEX" --- diff --git a/docs/user-guides/manage-enabled-coins.md b/docs/user-guides/manage-enabled-coins.md index 291b772..cea4a4d 100644 --- a/docs/user-guides/manage-enabled-coins.md +++ b/docs/user-guides/manage-enabled-coins.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 5 title: Manage Enabled Coins description: "How to manage enabled coins on BasicSwap DEX" --- @@ -10,12 +10,12 @@ import React from 'react'; # Manage Enabled Coins -BasicSwap DEX operates as a fully non-custodial exchange, giving you complete control over your assets throughout the trading process. This architecture provides significant security and privacy advantages but requires running a full node for each cryptocurrency you enable. +BasicSwap DEX operates as a fully non-custodial exchange, giving you complete control over your assets throughout the trading process. This architecture provides significant security and privacy advantages but requires running a full node for most enabled cryptocurrencies. Bitcoin and Litecoin support an optional [Electrum light wallet mode](/docs/user-guides/lightweight-modes), while Monero and Wownero support [remote node mode](/docs/user-guides/lightweight-modes#monero-remote-nodes), as lightweight alternatives to full nodes. This comprehensive guide explains all aspects of coin management within the BasicSwap environment, from enabling currencies to monitoring blockchain synchronization and managing wallets. :::info -In the current beta release, BasicSwap requires running full blockchain nodes locally for each enabled cryptocurrency. Solutions such as light nodes and third-party integrations are being considered and/or worked on by our community of open-source contributors and should eventually go live. +Most coins require running full blockchain nodes locally. However, **Bitcoin** and **Litecoin** support [Electrum light wallet mode](/docs/user-guides/lightweight-modes), while **Monero** and **Wownero** support [remote node mode](/docs/user-guides/lightweight-modes#monero-remote-nodes), allowing you to trade without downloading their full blockchains. See the [Lightweight Modes](/docs/user-guides/lightweight-modes) guide for details. ::: ## Enable Coins @@ -28,7 +28,11 @@ To trade with additional cryptocurrencies such as Bitcoin, Litecoin, or Monero, When operating BasicSwap, your device functions as a full node for each enabled cryptocurrency (such as Bitcoin), requiring complete blockchain synchronization before trading. -To check current synchronization progress: +:::tip +Coins running in [Electrum light wallet mode](/docs/user-guides/lightweight-modes) (available for Bitcoin and Litecoin) do not require blockchain synchronization. They connect to remote Electrum servers and are ready to use as soon as a server connection is established. Similarly, **Monero** and **Wownero** in [remote node mode](/docs/user-guides/lightweight-modes#monero-remote-nodes) connect to an external daemon instead of syncing locally. The wallet page will show connection status instead of a sync progress bar for these lightweight modes. +::: + +To check current synchronization progress for full node coins: 1. Access the Wallets page by selecting the `Wallets` tab on the BasicSwap interface. diff --git a/docs/user-guides/market-making.md b/docs/user-guides/market-making.md index e111269..1c5fbe9 100644 --- a/docs/user-guides/market-making.md +++ b/docs/user-guides/market-making.md @@ -1,5 +1,5 @@ --- -sidebar_position: 7 +sidebar_position: 8 title: GUI-Based Automated Market Making description: "How to use the integrated automated market making (AMM) tool in the BasicSwap DEX GUI." --- diff --git a/docs/user-guides/take-offer.md b/docs/user-guides/take-offer.md index 0e28013..f16e404 100644 --- a/docs/user-guides/take-offer.md +++ b/docs/user-guides/take-offer.md @@ -1,5 +1,5 @@ --- -sidebar_position: 6 +sidebar_position: 7 title: Take an Offer description: "How to take trading offers on BasicSwap DEX" --- From bea90d21c551a306cd337226f16bbb479ae6bacd Mon Sep 17 00:00:00 2001 From: cryptoguard Date: Sat, 31 Jan 2026 17:25:50 -0500 Subject: [PATCH 2/4] Add Web UI Authentication docs and rewrite AMM market-making guide --- docs/user-guides/install.md | 8 +- docs/user-guides/market-making.md | 446 ++++++++++++++++++---- docs/user-guides/web-ui-authentication.md | 177 +++++++++ 3 files changed, 552 insertions(+), 79 deletions(-) create mode 100644 docs/user-guides/web-ui-authentication.md diff --git a/docs/user-guides/install.md b/docs/user-guides/install.md index 5992233..9f9828f 100644 --- a/docs/user-guides/install.md +++ b/docs/user-guides/install.md @@ -234,7 +234,7 @@ After creating BasicSwap's Docker image, it's time to configure it to your prefe 7. **(Optional)** To use a [remote Monero node](/docs/user-guides/lightweight-modes#monero-remote-nodes) instead of running a local Monero daemon, prefix the command with `XMR_RPC_HOST` and `XMR_RPC_PORT` environment variables (e.g., `-e XMR_RPC_HOST="node2.monerodevs.org" -e XMR_RPC_PORT=18089`). - 8. Append `--client-auth-password=` to the below command to optionally enable client authentication to protect your web UI and API port access from unauthorized access. + 8. **(Optional)** To password-protect your web UI and API, append `--client-auth-password=` to the command below. This is recommended if your instance is accessible over a network (e.g., when using `--htmlhost=0.0.0.0`). See the [Web UI Authentication](/docs/user-guides/web-ui-authentication) guide for details on login, API access, password management, and disabling auth. 9. Execute the following command to configure your BasicSwap, adjusting it according to your preferences as described above. @@ -281,7 +281,7 @@ After creating BasicSwap's Docker image, it's time to configure it to your prefe 7. **(Optional)** To use a [remote Monero node](/docs/user-guides/lightweight-modes#monero-remote-nodes) instead of running a local Monero daemon, prefix the command with `XMR_RPC_HOST` and `XMR_RPC_PORT` environment variables (e.g., `-e XMR_RPC_HOST="node2.monerodevs.org" -e XMR_RPC_PORT=18089`). - 8. Append `--client-auth-password=` to the below command to optionally enable client authentication to protect your web UI and API port access from unauthorized access. + 8. **(Optional)** To password-protect your web UI and API, append `--client-auth-password=` to the command below. This is recommended if your instance is accessible over a network (e.g., when using `--htmlhost=0.0.0.0`). See the [Web UI Authentication](/docs/user-guides/web-ui-authentication) guide for details on login, API access, password management, and disabling auth. 9. Execute the following command to configure your BasicSwap, adjusting it according to your preferences as described above. @@ -458,7 +458,7 @@ Once the installation is complete, configure BasicSwap according to your require 7. **(Optional)** To use a [remote Monero node](/docs/user-guides/lightweight-modes#monero-remote-nodes) instead of running a local Monero daemon, prefix the command with `XMR_RPC_HOST` and `XMR_RPC_PORT` environment variables (e.g., `XMR_RPC_HOST="node2.monerodevs.org" XMR_RPC_PORT=18089`). - 8. Append `--client-auth-password=` to the below command to optionally enable client authentication to protect your web UI and API port access from unauthorized access. + 8. **(Optional)** To password-protect your web UI and API, append `--client-auth-password=` to the command below. This is recommended if your instance is accessible over a network (e.g., when using `--htmlhost=0.0.0.0`). See the [Web UI Authentication](/docs/user-guides/web-ui-authentication) guide for details on login, API access, password management, and disabling auth. 9. Execute the following command to configure your BasicSwap, adjusting it according to your preferences as described above. @@ -489,7 +489,7 @@ Once the installation is complete, configure BasicSwap according to your require 7. **(Optional)** To use a [remote Monero node](/docs/user-guides/lightweight-modes#monero-remote-nodes) instead of running a local Monero daemon, prefix the command with `XMR_RPC_HOST` and `XMR_RPC_PORT` environment variables (e.g., `XMR_RPC_HOST="node2.monerodevs.org" XMR_RPC_PORT=18089`). - 8. Append `--client-auth-password=` to the below command to optionally enable client authentication to protect your web UI and API port access from unauthorized access. + 8. **(Optional)** To password-protect your web UI and API, append `--client-auth-password=` to the command below. This is recommended if your instance is accessible over a network (e.g., when using `--htmlhost=0.0.0.0`). See the [Web UI Authentication](/docs/user-guides/web-ui-authentication) guide for details on login, API access, password management, and disabling auth. 9. Execute the following command to configure your BasicSwap, adjusting it according to your preferences as described above. diff --git a/docs/user-guides/market-making.md b/docs/user-guides/market-making.md index 1c5fbe9..007e31b 100644 --- a/docs/user-guides/market-making.md +++ b/docs/user-guides/market-making.md @@ -1,114 +1,410 @@ --- sidebar_position: 8 -title: GUI-Based Automated Market Making -description: "How to use the integrated automated market making (AMM) tool in the BasicSwap DEX GUI." +title: Automated Market Making (AMM) +description: "How to use the automated market making tool in BasicSwap DEX to provide liquidity and manage offers." --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import React from 'react'; -# GUI-Based Automated Market Making (AMM) +# Automated Market Making (AMM) -This guide explains how to use the Automated Market Making (AMM) tool integrated into the BasicSwap user interface. The AMM tool helps you provide liquidity with low effort by automating offer management. +BasicSwap includes an integrated Automated Market Making (AMM) tool that automates offer management on the decentralized order book. It handles offer republication, dynamic price adjustments, inventory tracking after partial fills, and optional automated bidding. This guide covers every aspect of the AMM: setup, configuration, rate strategies, automation, and troubleshooting. -## Key Features +:::caution +The AMM places real offers and spends real coins. Start with a single offer template and small amounts while learning the system. +::: -The AMM page incorporates all functionalities from the original companion script, alongside additional quality-of-life features. These include: +## How the AMM Works -* **Automatic Offer Republication**: Automatically republishes offers on the order book upon expiry. -* **Automatic Price Adjustments**: Adjusts offer rates based on the market price of each coin (a configurable percentage above or below market price). -* **Automatic Offer Size Adjustments**: Adjusts the amount of coins offered when previous offers are partially filled. -* **Market Buy/Sell**: Accepts offers up to a desired rate, then sets a new offer until the full desired amount is fulfilled. -* **Automatic Startup**: Starts the AMM tool automatically with BasicSwap. -* **GUI Configuration**: Configure all AMM settings directly from the user interface. -* **Swap Type Selection**: Choose between Secret Hash or Adaptor Signature swap types. -* **Price Source Selection**: Select the method used to determine automatic price adjustments. +The AMM runs as a standalone Python process (`createoffers.py`) managed through the AMM page in the BasicSwap web interface. It operates on a configurable loop (default: every 60 seconds) and performs the following on each cycle: -## How it Works +1. **Checks each enabled offer template** against your current wallet balance. +2. **Republishes expired offers** with updated rates and amounts. Offers on the SMSG network have a limited lifetime, so the AMM handles republication automatically. +3. **Adjusts offer sizes** after partial fills, reducing the amount by configurable increments. +4. **Recalculates rates** based on your chosen pricing strategy (market data, orderbook data, fixed rate, or a combination). +5. **Places bids** on existing offers if bid templates are configured (experimental feature). -### Automatic Republication of Offers +The AMM stores its configuration in `createoffers.json` and tracks active offers and bids in `createoffers_state.json`, both located in the `AMM/` subdirectory of your BasicSwap data folder. -BasicSwap offers have a set expiration time due to limitations of the SMSG P2P network. This previously required you to manually republish offers. With the AMM integration, this manual process is no longer necessary. You can set your offers within the tool and configure them for automatic republication upon expiry. +:::info +The AMM runs as a separate subprocess. It must be started manually from the AMM page or configured to start automatically with BasicSwap using the Autostart toggle. +::: -### Automatic Price Adjustments +## Getting Started -This feature automatically adjusts your offer's rate based on the current market price of both coins in the pair. +### 1. Open the AMM Page -You can choose from various methods to determine the market rate: -* **CoinGecko API**: Fetches the price from CoinGecko. -* **BasicSwap Order Book**: Uses the best rate of auto-accept offers on BasicSwap's own order book (no external connection). -* **Combined Methods**: Use different combinations of the above, including a static and/or fixed minimum rate. +Navigate to the **AMM** page in the BasicSwap web interface. This is the central control panel for all automated market making activity. -You can also set a **premium** on the market rate (a percentage above or below). This allows you to set offers that can guarantee a profit margin over the market rate at the time the offer was published. +### 2. Create an Offer Template -### Automatic Offer Size Adjustments +Click the **Add Offer** button to open the offer creation form. Fill in the following fields: -If you have a set inventory of a coin to offer, your offers need to reflect the remaining inventory after partial fills. For example, if you start with 100 Litecoins and a 20 Litecoin partial swap occurs, you are left with 80 Litecoins. The next time your offer is automatically republished, it will account for this reduced inventory. +* **Local Name/Label**: A private name for your reference (not visible to other users). +* **Maker Coin**: The coin you are selling. +* **Taker Coin**: The coin you want to receive. +* **Total Offer Amount**: How much of the maker coin to offer. +* **Minimum Rate**: The lowest rate you will accept, acting as a price floor. +* **Rate Tweak Percentage**: A percentage adjustment above or below the market rate (e.g., `2` adds a 2% premium). +* **Coin Rate/Price Calculation Method**: How the AMM determines the offer rate. See [Rate Adjustment Strategies](#rate-adjustment-strategies) for details. +* **Offer Expiry Time**: How long (in seconds) each offer stays on the order book before the AMM republishes it. Shorter values mean more frequent rate updates. +* **Minimum Bid Amount**: The smallest bid the AMM will auto-accept. +* **Offer Size Increment**: Controls how the AMM adjusts offer sizes after partial fills. See [Amount Step](#amount-step-privacy-feature) for details. +* **Swap Protocol**: Choose between Adaptor Signature or Secret Hash. +* **SMSG Identity**: The SMSG address to publish from. Use `auto` for a new random address per offer. -Once you configure your "Offer Size Increment" parameter, the AMM manages this entire process seamlessly in the background. +See the full [Offer Template Reference](#offer-template-reference) for all available parameters. -### Market Buys and Sells (Experimental) +### 3. Configure Global Settings (Optional) -The AMM tool introduces a "market buy/sell" functionality through the **Bids** function. This is currently an experimental feature. +Click **Global Configuration** to adjust timing parameters: -While the AMM's primary role is to automatically place dynamic offers, you can enable a feature to also place bids at a desired rate. If a bid's size exceeds the available quantity at a specific rate, the AMM will take the existing offer and then immediately place a new offer for the remaining amount of your initial bid. +* **Min/Max Seconds Between Offers**: Controls the random delay between publishing consecutive offers (default: 15-60 seconds). +* **Main Loop Delay**: How often the AMM checks all templates (default: 60 seconds, range: 10-1000). -**Example:** You want to acquire 10 Monero for 10 Litecoin (1.0 ratio). An offer for 5 Monero for 5 Litecoin exists at that rate. The AMM will first accept the entire 5 Monero offer. Then, it will place a new offer at the same rate for the remaining 5 Monero. +These defaults work well for most setups. See [Global Settings](#global-settings) for the full list. -#### How to Enable Market Buys and Sells +### 4. Start the AMM -As this feature is experimental, it requires manual activation. -1. Navigate to the **Settings** page. -2. In the **General** tab, activate both `debug` and `debug_ui`. +Click the **Start AMM** button. The AMM process will begin its loop, creating and managing offers based on your templates. You can monitor its activity in the **Log Viewer** at the bottom of the AMM page. -This feature will be integrated into the stable set of functionalities in the future, removing the need for manual activation. +* **Stop**: Gracefully shuts down the AMM process. +* **Force Start**: Kills any existing AMM processes and starts fresh. Use this if the AMM gets stuck. -## AMM User Interface Breakdown +### 5. Enable Autostart (Optional) -### Main Screen +Toggle the **Autostart** option to have the AMM start automatically whenever BasicSwap launches. This is useful for unattended operation. -The main AMM screen provides a central hub for managing your automated offers. +## Rate Adjustment Strategies -* **Offers Table**: Displays all your offers, their status (enabled/disabled), and main parameters. -* **Create New Offer**: Button to create a new automatic offer. -* **Refresh Button**: Refreshes the offer table with the most recent information. -* **Edit/Remove**: Options to edit or remove an existing offer. -* **AMM Control Center**: Start or stop all automatic offers. -* **Global Configuration**: Modify global AMM parameters. +The `adjust_rates_based_on_market` parameter controls how the AMM determines offer pricing. This can be set globally or overridden per offer template. Six modes are available: -### Create a New Offer +| Mode | Price Sources | Fallback Behavior | Use Case | +|---|---|---|---| +| `static` | None (uses `minrate` + `ratetweakpercent` only) | N/A | Fixed-price offers with no market tracking | +| `false` | CoinGecko only | Skips offer if CoinGecko is unavailable | Simple external price tracking | +| `true` | Higher of CoinGecko or orderbook | Falls back to whichever source is available | General use (recommended) | +| `all` | Requires both CoinGecko and orderbook | Skips offer if either source is unavailable | Conservative pricing with dual-source validation | +| `only` | BasicSwap orderbook only | Skips offer if no orderbook data exists | Privacy-focused (no external API calls) | +| `minrate` | Orderbook with `minrate` as floor | Uses `minrate` if no orderbook data exists | Orderbook pricing with a safety net | -This form allows you to define the parameters for a new automated offer. +### Mode Details -* **Local Name/Label**: A private name for your offer (not visible to others). -* **Enable/Disable Offer**: Controls if the offer is active. Disabled offers will not be republished. -* **Maker Coin**: The coin you are offering. -* **Taker Coin**: The coin you want to receive. -* **Total Offer Amount**: The total quantity of the maker coin you are offering. This amount is reduced after partial fills. -* **Minimum Rate**: The absolute lowest rate at which you are willing to sell. This protects against price drops. -* **Rate Tweak Percentage**: The percentage above or below the market price for your offer. E.g., a value of "1" on a $330 market price results in a $333 offer price ($330 + 1%). -* **Minimum Wallet Balance**: The minimum balance required in your wallet for the offer to be republished. -* **Offer Expiry Time (seconds)**: How long your offer remains on the order book before republication. Shorter durations mean more frequent rate updates. -* **SMSG Identity**: The SMSG identity to publish your offer from. Can be randomized for new offers. -* **Swap Protocol**: The swap protocol for your offer (Adaptor Signature or Secret Hash). -* **Minimum Bid Amount**: The minimum amount required for a bid on your offer to be automatically accepted. -* **Offer Size Adjustment Precision**: The precision of offer size adjustments after a partial fill. -* **Coin Rate/Price Calculation Method**: How coin rates are determined. "Static" disables automatic price adjustments. +**`static`**: Uses `minrate` as the base rate and applies `ratetweakpercent` on top. No market data is fetched. Best when you want a fixed, predictable price. -### Create a Bid +**`false`**: Fetches rates from the CoinGecko API. If CoinGecko is unreachable, the offer is skipped for that cycle. Best for straightforward market-rate tracking with an external source. -This form allows you to create automated bids to acquire coins. +**`true`**: Fetches rates from both CoinGecko and the BasicSwap orderbook, then uses whichever is higher. If one source is unavailable, the other is used as a fallback. This is the recommended default for most users because it balances reliability with market accuracy. -* **Local Name/Label**: A private name for your bid (not visible to others). -* **Enable/Disable Offer**: Controls if the bid is active. -* **Maker Coin**: The coin you are offering. -* **Taker Coin**: The coin you want to acquire. -* **Total Offer Amount**: The total quantity of the maker coin you are offering for this bid. -* **Maximum Rate**: The absolute highest rate you are willing to pay. This protects against price spikes. -* **Minimum Coin to Balance**: The minimum balance required in your wallet for a bid to be placed. -* **Max Concurrent**: Maximum number of active bids at once. -* **Offers to Bid On**: Filter which offer types to bid on: `auto_accept_only` (default), `all`, or `known_only`. -* **SMSG Identity**: The SMSG identity to publish your bid from. -* **Minimum Swap Amount**: The minimum number of coins required for a swap to take place. -* **Use Balance Bidding**: Automatically calculates the bid size based on your total coin balance minus the offer’s minimum amount. +**`all`**: Requires valid data from both CoinGecko and the orderbook. Uses the higher of the two rates. If either source is unavailable, the offer is skipped. Best when you want strict dual-source validation and are willing to skip cycles when data is incomplete. + +**`only`**: Uses only the rates from existing auto-accept offers on BasicSwap's own orderbook. No external API calls are made. If no matching offers exist on the orderbook, the offer is skipped. Best for users who want to avoid any external network connections. + +**`minrate`**: Uses the orderbook rate when available, but falls back to `minrate` if no orderbook data exists. This gives you orderbook-based pricing with a guaranteed floor price as a safety net. + +:::tip +For most users, `true` is the best starting point. If you want to avoid external API calls entirely, use `only`. If you want a fixed price with no market tracking, use `static`. +::: + +### Rate Tweak Percentage + +The `ratetweakpercent` parameter adjusts the final rate by a percentage: + +``` +final_rate = base_rate * (1 + ratetweakpercent / 100) +``` + +* A value of `2` adds a 2% premium above the market rate. +* A value of `-3` sets the rate 3% below market. +* The final rate never drops below `minrate`, regardless of the tweak value. + +**Example:** If the market rate for LTC/BTC is `0.003` and you set `ratetweakpercent` to `5`, the offer rate becomes `0.003 * 1.05 = 0.00315`. + +## Offer Template Reference + +| Parameter | Type | Default | Description | +|---|---|---|---| +| `name` | string | | Private label for this template (not visible to others) | +| `enabled` | bool | `true` | Whether this template is active | +| `coin_from` | string | | Coin you are selling (e.g., `"Litecoin"`) | +| `coin_to` | string | | Coin you want to receive (e.g., `"Bitcoin"`) | +| `amount` | float | | Base offer amount in `coin_from` units | +| `minrate` | float | | Absolute minimum acceptable rate (price floor) | +| `ratetweakpercent` | float | `0` | Percentage adjustment above or below market rate | +| `amount_variable` | bool | `true` | Allow partial fills (bidders can bid for less than the full amount) | +| `amount_step` | float | | Offer size increment for privacy (see below) | +| `min_coin_from_amt` | float | `0` | Minimum wallet balance to keep; offers stop if balance would drop below this | +| `offer_valid_seconds` | int | `3600` | How long each offer stays on the orderbook before republication | +| `automation_strategy` | string | `"accept_all"` | Bid acceptance mode: `accept_all`, `accept_known`, or `none` | +| `swap_type` | string | `"adaptor_sig"` | Swap protocol: `adaptor_sig` (Adaptor Signature) or `secret_hash` (Secret Hash) | +| `address` | string | `"auto"` | SMSG address to publish from (`"auto"` = random new address per offer) | +| `min_swap_amount` | float | | Minimum bid size the AMM will accept | +| `adjust_rates_based_on_market` | string | (global) | Per-offer override for the rate adjustment mode | + +### Amount Step (Privacy Feature) + +The `amount_step` parameter prevents counterparties from inferring your exact wallet balance through the size of your offers. + +Instead of publishing an offer for your full available balance, the AMM rounds the offer size down to the nearest multiple of `amount_step`. This means the offer amount changes in fixed increments rather than revealing precise balance information. + +**How it works:** + +1. If your wallet balance can cover the full template `amount` while keeping `min_coin_from_amt` in reserve, the offer is published at the full `amount`. No stepping occurs. +2. If your balance is too low for the full amount, the AMM calculates how much is available (`wallet_balance - min_coin_from_amt`), then rounds that down to the largest multiple of `amount_step` that fits. + +**Example:** Your template specifies `amount: 100`, `amount_step: 10`, and `min_coin_from_amt: 50` (keep at least 50 LTC in reserve). + +* If your wallet holds 200 LTC: `200 - 50 = 150` available, which covers the full 100. The offer is published at **100 LTC**. +* If your wallet holds 120 LTC: `120 - 50 = 70` available, which cannot cover 100. The AMM rounds 70 down to the nearest multiple of 10, resulting in a **70 LTC** offer. +* If your wallet holds 55 LTC: `55 - 50 = 5` available, which is less than one `amount_step` (10). The template is **skipped** for this cycle. + +:::info +The `amount_step` value must be between `0.001` and the template's `amount` value. Smaller increments give finer granularity but reveal more about your balance. Larger increments offer stronger privacy but less precise inventory usage. +::: + +## Automation Strategies and Identity Management + +### Bid Acceptance Strategies + +The `automation_strategy` field on each offer template controls how incoming bids are handled: + +* **`accept_all`**: Automatically accepts all incoming bids that meet the offer parameters. Provides maximum liquidity but gives you no control over who you trade with. +* **`accept_known`**: Only auto-accepts bids from SMSG identities that have completed at least one successful swap with you previously. More cautious; new counterparties are rejected. +* **`none`**: All bids require manual approval through the BasicSwap interface. Maximum control, but requires active monitoring. + +### Identity Filtering + +The AMM includes automatic protections against unreliable counterparties: + +* **Failed bid tracking**: Identities with more than 3 failed bids, where failures outnumber successes, are automatically skipped. +* **Per-identity overrides**: On the SMSG Addresses page, you can set an `automation_override` for specific identities: + * **Always Accept** (1): Bids from this identity are always auto-accepted, regardless of the offer's automation strategy. + * **Never Accept** (2): Bids from this identity are always rejected. + +### SMSG Addresses + +The `address` field in offer templates controls which SMSG identity publishes the offer: + +* **`"auto"`**: Generates a new random SMSG address for each offer. This provides better privacy because offers cannot be linked to a single identity. +* **Specific address**: Use a fixed SMSG address if you want a consistent identity across offers. This is useful if you want counterparties to recognize you and build swap history for the `accept_known` strategy. + +Manage your SMSG addresses on the **SMSG Addresses** page in the BasicSwap interface. + +## Bid Templates (Experimental) + +In addition to placing offers, the AMM can actively bid on existing offers to acquire coins. This "market buy/sell" feature is experimental and requires debug mode. + +### How Bids Work + +The AMM scans the orderbook for offers matching your bid template criteria. When a match is found, it places a bid. If the available quantity at your desired rate is less than your bid amount, the AMM takes what is available and then places a new offer for the remaining amount. + +**Example:** You want to acquire 10 XMR at a rate of 1.0 LTC/XMR. An offer for 5 XMR at that rate exists on the orderbook. The AMM bids on the 5 XMR offer, then publishes a new offer for the remaining 5 XMR. + +### How to Enable Bids + +Bid templates are an experimental feature that requires manual activation: + +1. Navigate to the **Settings** page. +2. In the **General** tab, enable both `debug` and `debug_ui`. +3. Return to the AMM page. The bid template section is now visible. + +### Bid Template Reference + +| Parameter | Type | Default | Description | +|---|---|---|---| +| `name` | string | | Private label for this bid template | +| `enabled` | bool | `true` | Whether this template is active | +| `coin_from` | string | | Coin you want to acquire | +| `coin_to` | string | | Coin you are spending | +| `amount` | float | | Amount of `coin_from` to acquire | +| `max_rate` | float | | Maximum rate you will pay (price ceiling) | +| `min_coin_to_balance` | float | | Minimum wallet balance to maintain for `coin_to` | +| `max_concurrent` | int | `1` | Maximum number of active bids at the same time | +| `offers_to_bid_on` | string | `"auto_accept_only"` | Which offers to target (see below) | +| `address` | string | `"auto"` | SMSG address to bid from | +| `min_swap_amount` | float | | Minimum swap size | +| `use_balance_bidding` | bool | `false` | Calculate bid size dynamically from wallet balance | + +### Offer Filtering for Bids + +The `offers_to_bid_on` parameter controls which offers the AMM will bid on: + +* **`auto_accept_only`** (default): Only bids on offers with automatic acceptance enabled. Avoids offers that require manual approval, reducing the chance of stuck bids. +* **`all`**: Bids on all available offers regardless of acceptance mode. +* **`known_only`**: Only bids on offers from identities with at least one successful swap in your history. + +### Balance Bidding + +When `use_balance_bidding` is enabled, the AMM calculates the bid amount dynamically: + +``` +bid_amount = wallet_balance - min_coin_to_balance +``` + +This is useful for liquidation strategies where you want to convert your entire available balance minus a reserve. + +### Pre-Offer Bidding + +Pre-offer bidding is an option on **offer templates** (not bid templates). It changes how the AMM processes an offer template by adding a step before the offer is published. + +Normally, the AMM publishes your offer and waits for someone else to bid on it. With `attempt_bids_first` enabled, the AMM first scans the orderbook for existing offers in the **reverse direction** (where someone else is selling what you want to buy) and bids on those. Whatever amount gets filled through bids is subtracted from the offer. The AMM then publishes an offer for the remaining amount, or skips the offer entirely if everything was filled. + +**Example:** Your offer template is set to sell 10 LTC for BTC. With `attempt_bids_first` enabled, the AMM finds an existing offer selling 4 BTC for LTC at an acceptable rate. It bids on that offer for 4 LTC worth, then publishes a new offer for the remaining 6 LTC. + +This is different from **bid templates**, which are standalone entries that only place bids and never create offers. Pre-offer bidding combines both behaviors in a single template. + +**Related parameters:** + +* **`attempt_bids_first`**: Set to `true` to enable this behavior on an offer template (default: `false`). +* **`bid_rate_tolerance`**: Percentage tolerance for accepting existing offer rates (e.g., `2.0` means the AMM will bid on offers with rates up to 2% worse than your target rate). +* **`max_bid_percentage`**: Maximum percentage of the template amount to fill through bids before publishing an offer (default: `50`, meaning at most half the amount can be filled via bids). +* **`bid_strategy`**: Controls filtering of which offers to bid on (`balanced`, `aggressive`, `conservative`). + +## Global Settings + +These parameters control the overall behavior of the AMM process. Configure them through the **Global Configuration** panel on the AMM page. + +| Setting | Description | Default | Range | +|---|---|---|---| +| `min_seconds_between_offers` | Minimum delay between publishing consecutive offers | `15` | | +| `max_seconds_between_offers` | Maximum delay between publishing consecutive offers | `60` | | +| `main_loop_delay` | Seconds between each AMM processing cycle | `60` | 10-1000 | +| `prune_state_delay` | Seconds between cleaning old entries from the state file | `120` | | +| `prune_state_after_seconds` | How long (in seconds) to keep old state data before pruning | `604800` (7 days) | | + +The delay between offers is randomized within the min/max range for each cycle. + +## Practical Examples + + + + A basic setup to sell Litecoin for Bitcoin at a 2% premium above market rate, with automatic price tracking and privacy-aware offer sizing. + + ```json title="Offer Template" + { + "name": "LTC to BTC", + "enabled": true, + "coin_from": "Litecoin", + "coin_to": "Bitcoin", + "amount": 50, + "minrate": 0.002, + "ratetweakpercent": 2, + "amount_variable": true, + "amount_step": 5, + "min_coin_from_amt": 10, + "offer_valid_seconds": 1800, + "automation_strategy": "accept_all", + "swap_type": "adaptor_sig", + "address": "auto", + "min_swap_amount": 0.5, + "adjust_rates_based_on_market": "true" + } + ``` + + **What this does:** Offers up to 50 LTC for BTC, adjusting the size in 5 LTC increments based on wallet balance. Keeps at least 10 LTC in reserve. Sets the rate 2% above the higher of CoinGecko or orderbook rates, with a floor of 0.002 BTC/LTC. Republishes every 30 minutes with updated pricing. Accepts all incoming bids of 0.5 LTC or more. + + + A setup for selling Particl for Monero using only orderbook data (no external API calls) and restricting trades to known counterparties. + + ```json title="Offer Template" + { + "name": "PART to XMR (private)", + "enabled": true, + "coin_from": "Particl", + "coin_to": "Monero", + "amount": 500, + "minrate": 0.01, + "ratetweakpercent": 1, + "amount_variable": true, + "amount_step": 50, + "min_coin_from_amt": 100, + "offer_valid_seconds": 3600, + "automation_strategy": "accept_known", + "swap_type": "adaptor_sig", + "address": "auto", + "min_swap_amount": 10, + "adjust_rates_based_on_market": "only" + } + ``` + + **What this does:** Offers up to 500 PART for XMR, in 50 PART increments. Uses only BasicSwap orderbook rates (no CoinGecko calls), with a floor of 0.01 XMR/PART. Only accepts bids from identities with successful swap history. Uses `adaptor_sig` for better on-chain privacy. Skips cycles where no orderbook data is available. + + + A setup with a fixed price and no market tracking, suitable when you have a specific rate in mind. + + ```json title="Offer Template" + { + "name": "BTC to LTC (fixed)", + "enabled": true, + "coin_from": "Bitcoin", + "coin_to": "Litecoin", + "amount": 0.1, + "minrate": 300, + "ratetweakpercent": 0, + "amount_variable": true, + "amount_step": 0.01, + "min_coin_from_amt": 0.01, + "offer_valid_seconds": 7200, + "automation_strategy": "accept_all", + "swap_type": "adaptor_sig", + "address": "auto", + "min_swap_amount": 0.005, + "adjust_rates_based_on_market": "static" + } + ``` + + **What this does:** Offers up to 0.1 BTC for LTC at a fixed rate of 300 LTC/BTC. No market data is fetched; the rate stays at `minrate` (300) with no tweak applied. Republishes every 2 hours. Accepts all bids of 0.005 BTC or more. + + + +## Limitations + +* **Single process**: Only one AMM process can run at a time. Starting a second instance will fail unless you stop or force-replace the first. +* **SMSG offer lifetime**: Offers on the SMSG network expire after the configured duration. The AMM handles republication, but there is a brief gap between expiration and the next cycle. +* **CoinGecko availability**: Rate modes that depend on CoinGecko (`false`, `true`, `all`) may skip cycles if the API is unreachable or rate-limited. +* **Counterparty reliability**: Swaps can still fail if the counterparty becomes unresponsive during the atomic swap process. The AMM tracks failed identities to avoid repeat issues. +* **Balance requirements**: If your wallet balance drops below `min_coin_from_amt`, the AMM stops publishing that offer template until the balance recovers. +* **Bid feature is experimental**: Bid templates require debug mode and may change in future releases. + +## Troubleshooting + +**AMM will not start** +* Check for orphan processes using the **Kill Orphans** button on the AMM page. +* Try **Force Start** to terminate any stuck processes and start fresh. +* Review the log viewer for error messages. + +**Offers are not appearing on the orderbook** +* Verify that the offer template is set to `enabled: true`. +* Check that your wallet balance exceeds `min_coin_from_amt` plus the offer amount (or the smallest `amount_step` multiple). +* If using a rate mode that depends on external data (`false`, `true`, `all`, `only`, `minrate`), confirm the required data source is available. The log viewer will show "skipping" messages when data is missing. + +**Rates seem incorrect** +* Verify the sign and magnitude of `ratetweakpercent`. A positive value increases the rate; a negative value decreases it. +* Confirm which rate mode is active for the template. Check the global setting and any per-offer override. +* If using CoinGecko-dependent modes, check that the API is reachable from your machine. + +**Bids are not being placed** +* Confirm that debug mode is enabled: Settings > General > enable both `debug` and `debug_ui`. +* Check that the bid template is enabled and `max_concurrent` has not been reached. +* Verify that matching offers exist on the orderbook within your `max_rate` threshold. + +**AMM process keeps stopping** +* Open the log viewer and look for error messages. +* If client authentication is enabled on BasicSwap, ensure the `auth` field in the AMM global settings matches your credentials. +* Check that the BasicSwap API is responding (the AMM communicates with BasicSwap over its local API). + +## AMM Interface Reference + +The AMM page provides the following controls: + +* **Start / Stop / Force Start**: Manage the AMM process lifecycle. +* **Autostart Toggle**: Enable or disable automatic startup with BasicSwap. +* **Offer Templates Table**: View, add, edit, and delete offer templates. Each row shows the template name, coin pair, amount, rate settings, and enabled status. +* **Bid Templates Table**: (Visible in debug mode) View, add, edit, and delete bid templates. +* **Global Configuration Panel**: Adjust timing and delay settings. +* **Config JSON Editor**: Directly edit the raw `createoffers.json` configuration file for advanced use cases. +* **State File Viewer**: Inspect the current `createoffers_state.json` to see tracked offers and bids. +* **Log Viewer**: View real-time output from the AMM process, including errors, offer creation events, and rate calculations. +* **Debug Mode Toggle**: Enable or disable debug output for more detailed logging. diff --git a/docs/user-guides/web-ui-authentication.md b/docs/user-guides/web-ui-authentication.md new file mode 100644 index 0000000..5cf1e94 --- /dev/null +++ b/docs/user-guides/web-ui-authentication.md @@ -0,0 +1,177 @@ +--- +sidebar_position: 10 +title: Web UI Authentication +description: "How to password-protect your BasicSwap web interface and API" +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Web UI Authentication + +BasicSwap can require a password to access the web interface and API. This protects your instance from unauthorized access, which is particularly important if your BasicSwap is reachable over a network (for example, when running with `--htmlhost=0.0.0.0`). + +When authentication is enabled, every page except the login screen requires a valid session or API credentials. Without them, visitors are redirected to the login page. + +:::caution +BasicSwap's built-in HTTP server does not use TLS. If your instance is accessible from outside `localhost`, your password is sent in cleartext unless you put a reverse proxy (e.g., Nginx, Caddy) with HTTPS in front of it. +::: + +## Enable Authentication + +### During Initial Setup + +Add the `--client-auth-password` flag when running `basicswap-prepare` for the first time. + + + + Append the flag to your `basicswap-prepare` command: + + ```bash title="Terminal" + docker run --rm -t --name swap_prepare \ + -v $COINDATA_PATH:/coindata i_swapclient \ + basicswap-prepare --datadir=/coindata \ + --withcoins=monero,bitcoin \ + --client-auth-password=YOUR_PASSWORD + ``` + + + Append the flag to your `basicswap-prepare` command: + + ```bash title="Terminal" + basicswap-prepare --datadir=$SWAP_DATADIR \ + --withcoins=monero,bitcoin \ + --client-auth-password=YOUR_PASSWORD + ``` + + + +### On an Existing Installation + +You can enable authentication at any time by re-running `basicswap-prepare` with the `--client-auth-password` flag. BasicSwap must be stopped first. + + + + ```bash title="Terminal" + docker-compose stop + docker-compose run --rm swapclient \ + basicswap-prepare --datadir=/coindata \ + --client-auth-password=YOUR_PASSWORD + docker-compose up -d + ``` + + + Stop BasicSwap, then run: + + ```bash title="Terminal" + basicswap-prepare --datadir=$SWAP_DATADIR \ + --client-auth-password=YOUR_PASSWORD + ``` + + Start BasicSwap again afterward. + + + +The password is hashed and stored as `client_auth_hash` in `basicswap_settings.json`. The plaintext password is never saved. + +## Login + +Once authentication is enabled, opening the BasicSwap web UI redirects you to the login page. Enter the password you set during setup. + +After a successful login, a session cookie is created. The session is valid for 60 minutes and resets its expiration each time you interact with the interface. If you are idle for more than 60 minutes, you will need to log in again. + +:::info +If BasicSwap detects that the web UI is accessible from a non-local address, the login page displays a warning about sending passwords over plain HTTP. For remote deployments, set up HTTPS through a reverse proxy. +::: + +## API Authentication + +The BasicSwap JSON API (endpoints under `/json/`) is protected by the same password. There are two ways to authenticate API requests. + +### HTTP Basic Auth + +Use HTTP Basic Authentication with any username (it is ignored) and the auth password. This is the simplest method for scripts and command-line tools. + +```bash title="Terminal" +curl -u :YOUR_PASSWORD http://localhost:12700/json/wallets +``` + +The colon before the password indicates an empty username. + +### Session-Based Auth + +You can also obtain a session by sending a POST request to `/login` with JSON: + +```bash title="Terminal" +curl -X POST http://localhost:12700/login \ + -H "Content-Type: application/json" \ + -d '{"password": "YOUR_PASSWORD"}' \ + -c cookies.txt + +curl -b cookies.txt http://localhost:12700/json/wallets +``` + +The response includes a `basicswap_session_id` cookie that you can reuse for subsequent requests. + +## Change Password + +There are two ways to change the authentication password. + +**Via the web UI:** Navigate to `/changepassword` while logged in. Enter your current password and a new one. The new password must meet these requirements: + +* At least 8 characters +* At least one uppercase letter (A-Z) +* At least one lowercase letter (a-z) +* At least one number (0-9) + +**Via the command line:** Stop BasicSwap and re-run `basicswap-prepare` with the new password: + + + + ```bash title="Terminal" + docker-compose stop + docker-compose run --rm swapclient \ + basicswap-prepare --datadir=/coindata \ + --client-auth-password=NEW_PASSWORD + docker-compose up -d + ``` + + + ```bash title="Terminal" + basicswap-prepare --datadir=$SWAP_DATADIR \ + --client-auth-password=NEW_PASSWORD + ``` + + + +## Disable Authentication + +To remove password protection entirely, use the `--disable-client-auth` flag. BasicSwap must be stopped first. + + + + ```bash title="Terminal" + docker-compose stop + docker-compose run --rm swapclient \ + basicswap-prepare --datadir=/coindata \ + --disable-client-auth + docker-compose up -d + ``` + + + ```bash title="Terminal" + basicswap-prepare --datadir=$SWAP_DATADIR \ + --disable-client-auth + ``` + + + +This removes the `client_auth_hash` entry from `basicswap_settings.json`. After restarting, the web UI and API are accessible without a password. + +## Security Notes + +* The authentication password is hashed using RFC 2440 (the same scheme used by Tor) before being stored. The plaintext password is never written to disk. +* Sessions are stored in memory. Restarting BasicSwap invalidates all active sessions, requiring everyone to log in again. +* BasicSwap serves HTTP, not HTTPS. On `localhost` this is fine, but for remote access, place a reverse proxy with TLS (Nginx, Caddy, etc.) in front of BasicSwap. +* When using `--htmlhost=0.0.0.0`, your web UI is exposed to the entire local network (or wider, depending on firewall rules). Always enable authentication in this configuration. +* The login page, static assets, error pages, and info pages are exempt from authentication. All other pages and API endpoints require a valid session or Basic Auth credentials. From 58b2e8791fe25811a3411e56c63a8960d6e21634 Mon Sep 17 00:00:00 2001 From: cryptoguard Date: Mon, 2 Feb 2026 13:43:26 -0500 Subject: [PATCH 3/4] Changes following PR review by OX --- docs/user-guides/lightweight-modes.md | 40 ++++++++++++--------------- 1 file changed, 18 insertions(+), 22 deletions(-) diff --git a/docs/user-guides/lightweight-modes.md b/docs/user-guides/lightweight-modes.md index 5e21391..c826566 100644 --- a/docs/user-guides/lightweight-modes.md +++ b/docs/user-guides/lightweight-modes.md @@ -106,13 +106,13 @@ You cannot switch connection modes while the coin has active swaps in progress. #### Via Configuration File -You can manually edit the `basicswap_settings.json` file to enable Electrum mode: +You can manually edit the `basicswap.json` file to enable Electrum mode: 1. Stop BasicSwap. -2. Open `basicswap_settings.json` in a text editor (located in your data directory). +2. Open `basicswap.json` in a text editor (located in your data directory). 3. Under the coin's `chainclients` section, set the following: -```json title="basicswap_settings.json" +```json title="basicswap.json" { "chainclients": { "bitcoin": { @@ -131,19 +131,14 @@ You can switch between full node (RPC) and Electrum mode at any time, provided t #### Automatic Fund Transfer -By default, **auto-transfer on mode switch** is enabled. When you switch modes, BasicSwap will automatically sweep your funds from the old wallet to the new one: - -- **RPC → Electrum:** Funds are swept from your full node wallet to Electrum-derived addresses. -- **Electrum → RPC:** Funds are swept from Electrum addresses back to your full node wallet. - -A standard network fee is deducted from the sweep transaction. +You can enable **auto-transfer on mode switch** in the Settings page. When enabled and you switch from Electrum back to RPC mode, BasicSwap will automatically sweep your funds from Electrum addresses back to your full node wallet. A standard network fee is deducted from the sweep transaction. #### Manual Fund Transfer -If you disable auto-transfer (`auto_transfer_on_mode_switch: false`), you must manually move your funds between wallets when switching modes. +If auto-transfer is not enabled, you must manually move your funds between wallets when switching modes. :::warning -When auto-transfer is disabled, your old wallet's funds will **not** be accessible from the new mode until you manually transfer them. Make sure to move your funds before or after switching, or enable auto-transfer to have this handled automatically. +Without auto-transfer, your old wallet's funds will **not** be accessible from the new mode until you manually transfer them. Make sure to move your funds before or after switching, or enable auto-transfer in Settings to have this handled automatically. ::: ### Custom Electrum Servers @@ -187,9 +182,9 @@ Servers are specified in `host:port:ssl` format: **Via the Web UI:** Navigate to Settings, select the coin, and enter your servers in the clearnet or onion server text fields (one per line). -**Via configuration file:** Add the `electrum_clearnet_servers` and/or `electrum_onion_servers` lists to the coin's section in `basicswap_settings.json`: +**Via configuration file:** Add the `electrum_clearnet_servers` and/or `electrum_onion_servers` lists to the coin's section in `basicswap.json`: -```json title="basicswap_settings.json" +```json title="basicswap.json" { "chainclients": { "bitcoin": { @@ -250,7 +245,7 @@ BasicSwap automatically monitors server health and handles failover: | `electrum_clearnet_servers` | list | (built-in defaults) | Custom clearnet servers in `host:port:ssl` format | | `electrum_onion_servers` | list | `[]` | Custom `.onion` servers for Tor | | `electrum_poll_interval` | int | `10` | Polling interval in seconds for wallet updates | -| `auto_transfer_on_mode_switch` | bool | `true` | Automatically sweep funds when switching between RPC and Electrum | +| `auto_transfer_on_mode_switch` | bool | `false` | Automatically sweep funds when switching from Electrum to RPC | | `address_gap_limit` | int | `20` | BIP44 gap limit for address derivation and discovery | ### Electrum Limitations @@ -458,23 +453,24 @@ ssh -N -R 18089:localhost:18089 user@LOCAL_BSX_IP ### Trusted vs Untrusted Daemon -BasicSwap automatically determines whether to treat the remote daemon as trusted or untrusted based on the daemon's IP address: +By default, BasicSwap treats remote daemons as **trusted**. The wallet skips some verification steps for better performance in this mode. + +You can opt in to **auto mode**, which determines trust based on the daemon's IP address: -- **Trusted (private IPs):** `127.x.x.x`, `10.x.x.x`, `172.16-31.x.x`, `192.168.x.x`, `localhost`, and `*.local` addresses are treated as trusted. The wallet skips some verification steps for better performance. +- **Trusted (private IPs):** `127.x.x.x`, `10.x.x.x`, `172.16-31.x.x`, `192.168.x.x`, `localhost`, and `*.local` addresses are treated as trusted. - **Untrusted (public IPs):** All other addresses are treated as untrusted. The wallet performs additional verification to guard against a potentially dishonest daemon. -You can override the auto-detection: +To change the trust mode: -- **During setup:** Add `--trustremotenode` to the `basicswap-prepare` command. -- **In configuration:** Set `"trusted_daemon": true` or `"trusted_daemon": false` in the Monero section of `basicswap.json`. +- **In configuration:** Set `"trusted_daemon": "auto"` or `"trusted_daemon": false` in the Monero section of `basicswap.json`. :::warning -Only mark a daemon as trusted if you fully control it. A malicious trusted daemon could provide false blockchain data to your wallet. +Any remote node, even in untrusted mode, can provide bogus data including wildly inflated fees, which can cause permanent loss of funds. Only use nodes that you trust. ::: ### Automatic Daemon Selection -BasicSwap can automatically select from a list of remote Monero daemons, providing failover if one becomes unavailable. +BasicSwap can automatically select from a list of remote Monero daemons, providing failover if one becomes unavailable. Unlike Electrum mode (which switches servers live), Monero daemon selection only happens at startup. To enable automatic daemon selection: @@ -516,7 +512,7 @@ No additional configuration is needed beyond enabling Tor on your BasicSwap inst | `rpcport` | int | `29798` | Remote daemon RPC port (public nodes typically use `18081` or `18089`) | | `rpcuser` | string | `""` | Optional RPC authentication username | | `rpcpassword` | string | `""` | Optional RPC authentication password | -| `trusted_daemon` | string | `"auto"` | `true`, `false`, or `"auto"` (auto-detects based on IP) | +| `trusted_daemon` | bool/string | `true` | `true` (bool), `false` (bool), or `"auto"` (string, auto-detects based on IP) | | `automatically_select_daemon` | bool | `false` | Enable automatic daemon selection from URL list | | `remote_daemon_urls` | list | `[]` | List of `host:port` strings for daemon failover | | `fee_priority` | int | `0` | Transaction fee priority: 0=auto, 1=slow, 2=normal, 3=fast | From 9164116b1435d4bcd74fedd193b1828550ed8391 Mon Sep 17 00:00:00 2001 From: cryptoguard Date: Mon, 9 Feb 2026 17:41:02 -0500 Subject: [PATCH 4/4] Add interactive Coin Compatibility Matrix page --- docs/about/coin-compatibility.md | 799 +++++++++++++++++++++++++++++++ docs/about/under-the-hood.md | 6 +- docs/intro.md | 4 + 3 files changed, 808 insertions(+), 1 deletion(-) create mode 100644 docs/about/coin-compatibility.md diff --git a/docs/about/coin-compatibility.md b/docs/about/coin-compatibility.md new file mode 100644 index 0000000..f302b0c --- /dev/null +++ b/docs/about/coin-compatibility.md @@ -0,0 +1,799 @@ +--- +sidebar_position: 3 +title: Coin Compatibility Matrix +description: "Complete matrix showing which coins can be swapped with each other and supported swap types" +--- + + + +
      + +
      +
      +
      +
      +
      A · Adaptor Signature
      +
      Advanced cryptographic protocol
      +
      +
      +
      +
      +
      +
      H · Secret Hash
      +
      Time-locked contract (HTLC)
      +
      +
      +
      +
      +
      +
      V · VES Protocol
      +
      Verifiably encrypted signatures
      +
      +
      +
      +
      +
      +
      - · Not Compatible
      +
      Pair not supported
      +
      +
      +
      + +
      +
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Maker · You Send
      BTCBCHDASHDCRDOGEFIROLTCNMCPARTPART ANONPART BLINDPIVXWOWXMR
      Taker · You ReceiveBTC
      -
      A
      BTC ↔ BCH
      Adaptor Signature
      A,H
      BTC ↔ DASH
      AdaptorHash
      A,H
      BTC ↔ DCR
      AdaptorHash
      A
      BTC ↔ DOGE
      Adaptor Signature
      A
      BTC ↔ FIRO
      Adaptor Signature
      A,H
      BTC ↔ LTC
      AdaptorHash
      A,H
      BTC ↔ NMC
      AdaptorHash
      A,H
      BTC ↔ PART
      AdaptorHash
      A
      BTC ↔ PART ANON
      Adaptor Signature
      A
      BTC ↔ PART BLIND
      Adaptor Signature
      A,H
      BTC ↔ PIVX
      AdaptorHash
      A
      BTC ↔ WOW
      Adaptor Signature
      A
      BTC ↔ XMR
      Adaptor Signature
      BCH
      A
      BCH ↔ BTC
      Adaptor Signature
      -
      -
      BCH ↔ DASH
      Not Compatible
      A
      BCH ↔ DCR
      Adaptor Signature
      -
      BCH ↔ DOGE
      Not Compatible
      -
      BCH ↔ FIRO
      Not Compatible
      A
      BCH ↔ LTC
      Adaptor Signature
      A
      BCH ↔ NMC
      Adaptor Signature
      A
      BCH ↔ PART
      Adaptor Signature
      V
      BCH ↔ PART ANON
      VES Protocol
      A
      BCH ↔ PART BLIND
      Adaptor Signature
      -
      BCH ↔ PIVX
      Not Compatible
      V
      BCH ↔ WOW
      VES Protocol
      V
      BCH ↔ XMR
      VES Protocol
      DASH
      A,H
      DASH ↔ BTC
      AdaptorHash
      -
      DASH ↔ BCH
      Not Compatible
      -
      A,H
      DASH ↔ DCR
      AdaptorHash
      -
      DASH ↔ DOGE
      Not Compatible
      -
      DASH ↔ FIRO
      Not Compatible
      A,H
      DASH ↔ LTC
      AdaptorHash
      A,H
      DASH ↔ NMC
      AdaptorHash
      A,H
      DASH ↔ PART
      AdaptorHash
      -
      DASH ↔ PART ANON
      Not Compatible
      A
      DASH ↔ PART BLIND
      Adaptor Signature
      H
      DASH ↔ PIVX
      Secret Hash
      -
      DASH ↔ WOW
      Not Compatible
      -
      DASH ↔ XMR
      Not Compatible
      DCR
      A,H
      DCR ↔ BTC
      AdaptorHash
      A
      DCR ↔ BCH
      Adaptor Signature
      A,H
      DCR ↔ DASH
      AdaptorHash
      -
      A
      DCR ↔ DOGE
      Adaptor Signature
      A
      DCR ↔ FIRO
      Adaptor Signature
      A,H
      DCR ↔ LTC
      AdaptorHash
      A,H
      DCR ↔ NMC
      AdaptorHash
      A,H
      DCR ↔ PART
      AdaptorHash
      A
      DCR ↔ PART ANON
      Adaptor Signature
      A
      DCR ↔ PART BLIND
      Adaptor Signature
      A,H
      DCR ↔ PIVX
      AdaptorHash
      A
      DCR ↔ WOW
      Adaptor Signature
      A
      DCR ↔ XMR
      Adaptor Signature
      DOGE
      A
      DOGE ↔ BTC
      Adaptor Signature
      -
      DOGE ↔ BCH
      Not Compatible
      -
      DOGE ↔ DASH
      Not Compatible
      A
      DOGE ↔ DCR
      Adaptor Signature
      -
      -
      DOGE ↔ FIRO
      Not Compatible
      A
      DOGE ↔ LTC
      Adaptor Signature
      A
      DOGE ↔ NMC
      Adaptor Signature
      A
      DOGE ↔ PART
      Adaptor Signature
      -
      DOGE ↔ PART ANON
      Not Compatible
      A
      DOGE ↔ PART BLIND
      Adaptor Signature
      -
      DOGE ↔ PIVX
      Not Compatible
      -
      DOGE ↔ WOW
      Not Compatible
      -
      DOGE ↔ XMR
      Not Compatible
      FIRO
      A
      FIRO ↔ BTC
      Adaptor Signature
      -
      FIRO ↔ BCH
      Not Compatible
      -
      FIRO ↔ DASH
      Not Compatible
      A
      FIRO ↔ DCR
      Adaptor Signature
      -
      FIRO ↔ DOGE
      Not Compatible
      -
      A
      FIRO ↔ LTC
      Adaptor Signature
      A
      FIRO ↔ NMC
      Adaptor Signature
      A
      FIRO ↔ PART
      Adaptor Signature
      -
      FIRO ↔ PART ANON
      Not Compatible
      A
      FIRO ↔ PART BLIND
      Adaptor Signature
      -
      FIRO ↔ PIVX
      Not Compatible
      -
      FIRO ↔ WOW
      Not Compatible
      -
      FIRO ↔ XMR
      Not Compatible
      LTC
      A,H
      LTC ↔ BTC
      AdaptorHash
      A
      LTC ↔ BCH
      Adaptor Signature
      A,H
      LTC ↔ DASH
      AdaptorHash
      A,H
      LTC ↔ DCR
      AdaptorHash
      A
      LTC ↔ DOGE
      Adaptor Signature
      A
      LTC ↔ FIRO
      Adaptor Signature
      -
      A,H
      LTC ↔ NMC
      AdaptorHash
      A,H
      LTC ↔ PART
      AdaptorHash
      A
      LTC ↔ PART ANON
      Adaptor Signature
      A
      LTC ↔ PART BLIND
      Adaptor Signature
      A,H
      LTC ↔ PIVX
      AdaptorHash
      A
      LTC ↔ WOW
      Adaptor Signature
      A
      LTC ↔ XMR
      Adaptor Signature
      NMC
      A,H
      NMC ↔ BTC
      AdaptorHash
      A
      NMC ↔ BCH
      Adaptor Signature
      A,H
      NMC ↔ DASH
      AdaptorHash
      A,H
      NMC ↔ DCR
      AdaptorHash
      A
      NMC ↔ DOGE
      Adaptor Signature
      A
      NMC ↔ FIRO
      Adaptor Signature
      A,H
      NMC ↔ LTC
      AdaptorHash
      -
      A,H
      NMC ↔ PART
      AdaptorHash
      A
      NMC ↔ PART ANON
      Adaptor Signature
      A
      NMC ↔ PART BLIND
      Adaptor Signature
      A,H
      NMC ↔ PIVX
      AdaptorHash
      A
      NMC ↔ WOW
      Adaptor Signature
      A
      NMC ↔ XMR
      Adaptor Signature
      PART
      A,H
      PART ↔ BTC
      AdaptorHash
      A
      PART ↔ BCH
      Adaptor Signature
      A,H
      PART ↔ DASH
      AdaptorHash
      A,H
      PART ↔ DCR
      AdaptorHash
      A
      PART ↔ DOGE
      Adaptor Signature
      A
      PART ↔ FIRO
      Adaptor Signature
      A,H
      PART ↔ LTC
      AdaptorHash
      A,H
      PART ↔ NMC
      AdaptorHash
      -
      A
      PART ↔ PART ANON
      Adaptor Signature
      A
      PART ↔ PART BLIND
      Adaptor Signature
      A,H
      PART ↔ PIVX
      AdaptorHash
      A
      PART ↔ WOW
      Adaptor Signature
      A
      PART ↔ XMR
      Adaptor Signature
      PART ANON
      A
      PART ANON ↔ BTC
      Adaptor Signature
      V
      PART ANON ↔ BCH
      VES Protocol
      -
      PART ANON ↔ DASH
      Not Compatible
      A
      PART ANON ↔ DCR
      Adaptor Signature
      -
      PART ANON ↔ DOGE
      Not Compatible
      -
      PART ANON ↔ FIRO
      Not Compatible
      A
      PART ANON ↔ LTC
      Adaptor Signature
      A
      PART ANON ↔ NMC
      Adaptor Signature
      A
      PART ANON ↔ PART
      Adaptor Signature
      -
      A
      PART ANON ↔ PART BLIND
      Adaptor Signature
      -
      PART ANON ↔ PIVX
      Not Compatible
      -
      PART ANON ↔ WOW
      Not Compatible
      -
      PART ANON ↔ XMR
      Not Compatible
      PART BLIND
      A
      PART BLIND ↔ BTC
      Adaptor Signature
      A
      PART BLIND ↔ BCH
      Adaptor Signature
      A
      PART BLIND ↔ DASH
      Adaptor Signature
      A
      PART BLIND ↔ DCR
      Adaptor Signature
      A
      PART BLIND ↔ DOGE
      Adaptor Signature
      A
      PART BLIND ↔ FIRO
      Adaptor Signature
      A
      PART BLIND ↔ LTC
      Adaptor Signature
      A
      PART BLIND ↔ NMC
      Adaptor Signature
      A
      PART BLIND ↔ PART
      Adaptor Signature
      A
      PART BLIND ↔ PART ANON
      Adaptor Signature
      -
      -
      PART BLIND ↔ PIVX
      Not Compatible
      A
      PART BLIND ↔ WOW
      Adaptor Signature
      A
      PART BLIND ↔ XMR
      Adaptor Signature
      PIVX
      A,H
      PIVX ↔ BTC
      AdaptorHash
      -
      PIVX ↔ BCH
      Not Compatible
      H
      PIVX ↔ DASH
      Secret Hash
      A,H
      PIVX ↔ DCR
      AdaptorHash
      -
      PIVX ↔ DOGE
      Not Compatible
      -
      PIVX ↔ FIRO
      Not Compatible
      A,H
      PIVX ↔ LTC
      AdaptorHash
      A,H
      PIVX ↔ NMC
      AdaptorHash
      A,H
      PIVX ↔ PART
      AdaptorHash
      -
      PIVX ↔ PART ANON
      Not Compatible
      -
      PIVX ↔ PART BLIND
      Not Compatible
      -
      -
      PIVX ↔ WOW
      Not Compatible
      -
      PIVX ↔ XMR
      Not Compatible
      WOW
      A
      WOW ↔ BTC
      Adaptor Signature
      V
      WOW ↔ BCH
      VES Protocol
      -
      WOW ↔ DASH
      Not Compatible
      A
      WOW ↔ DCR
      Adaptor Signature
      -
      WOW ↔ DOGE
      Not Compatible
      -
      WOW ↔ FIRO
      Not Compatible
      A
      WOW ↔ LTC
      Adaptor Signature
      A
      WOW ↔ NMC
      Adaptor Signature
      A
      WOW ↔ PART
      Adaptor Signature
      -
      WOW ↔ PART ANON
      Not Compatible
      A
      WOW ↔ PART BLIND
      Adaptor Signature
      -
      WOW ↔ PIVX
      Not Compatible
      -
      -
      WOW ↔ XMR
      Not Compatible
      XMR
      A
      XMR ↔ BTC
      Adaptor Signature
      V
      XMR ↔ BCH
      VES Protocol
      -
      XMR ↔ DASH
      Not Compatible
      A
      XMR ↔ DCR
      Adaptor Signature
      -
      XMR ↔ DOGE
      Not Compatible
      -
      XMR ↔ FIRO
      Not Compatible
      A
      XMR ↔ LTC
      Adaptor Signature
      A
      XMR ↔ NMC
      Adaptor Signature
      A
      XMR ↔ PART
      Adaptor Signature
      -
      XMR ↔ PART ANON
      Not Compatible
      A
      XMR ↔ PART BLIND
      Adaptor Signature
      -
      XMR ↔ PIVX
      Not Compatible
      -
      XMR ↔ WOW
      Not Compatible
      -
      +
      +
      + +
      +

      Coin Categories

      +
      +
      +
      +

      Scriptless

      +
      +
      XMR · WOW · PART_ANON · FIRO · DOGE
      +

      + Require adaptor signatures. Lack native scripting but participate through advanced cryptographic protocols. Cannot swap with other scriptless coins. +

      +
      + +
      +
      +

      Adaptor-Only

      +
      +
      PART_BLIND · BCH
      +

      + Exclusively use adaptor signatures. Can swap with scriptless and regular coins. Require Segwit in counterparty coins. +

      +
      + +
      +
      +

      No-Segwit

      +
      +
      PIVX · DASH
      +

      + Support both secret hash and adaptor signatures with compatible coins. Cannot swap with scriptless coins. Adaptor swaps not possible between no-segwit coins. +

      +
      + +
      +
      +

      Regular

      +
      +
      PART · BTC · LTC · DCR · NMC
      +

      + Maximum flexibility with both adaptor signatures and secret hash swaps. Adapt to counterparty coin requirements automatically. +

      +
      +
      +
      + +
      diff --git a/docs/about/under-the-hood.md b/docs/about/under-the-hood.md index 93df072..e03620e 100644 --- a/docs/about/under-the-hood.md +++ b/docs/about/under-the-hood.md @@ -56,13 +56,17 @@ BasicSwap implements two distinct atomic swap protocols: HTLC ('Secret Hash') an

      PTLC Protocol (Adaptor Sigs)

      -

      Employs adaptor signatures to enable atomic swaps with unscriptable coins like Monero while providing better privacy.

      +

      Employs adaptor signatures to enable atomic swaps with unscriptable coins like Monero while providing better privacy.

      +:::tip Coin Compatibility +Different coins support different swap protocols based on their technical capabilities. Check the [Coin Compatibility Matrix](/docs/about/coin-compatibility) to see which swap types are available for specific trading pairs. +::: + ### Technical Implementation Both protocols are open-source developments from the broader cryptocurrency community and their scope is intentionally narrow — they do not match orders or provide a complete DEX framework. Instead, they focus exclusively on secure, trustless execution of exchanges directly on the respective blockchains without intermediaries. diff --git a/docs/intro.md b/docs/intro.md index 9a05325..9d2715d 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -167,6 +167,10 @@ BasicSwap's primary function is to help users establish a secure communication c

      +:::tip Coin Compatibility Matrix +View the complete [Coin Compatibility Matrix](/docs/about/coin-compatibility) to see which coins can be swapped with each other and what swap types (Adaptor Signature, Secret Hash, or VES) are supported for each trading pair. +::: +