From 8507665569aad00705a5bf87432f389df11b8829 Mon Sep 17 00:00:00 2001 From: cryptoguard Date: Sat, 31 Jan 2026 11:47:35 -0500 Subject: [PATCH 1/3] 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 48c1681bc0870c2be3ceb1d4e71f9e30df906a2a Mon Sep 17 00:00:00 2001 From: cryptoguard Date: Mon, 2 Feb 2026 13:43:26 -0500 Subject: [PATCH 2/3] 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 de0c0611b4cddb5d70ab31a12888d381f500fbfd Mon Sep 17 00:00:00 2001 From: cryptoguard Date: Mon, 9 Feb 2026 17:41:02 -0500 Subject: [PATCH 3/3] 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. +::: +