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 fad1f34d6e4dd1f748313b0a354d1d828d43b33f Mon Sep 17 00:00:00 2001 From: cryptoguard Date: Tue, 17 Feb 2026 17:06:12 -0500 Subject: [PATCH 3/3] Add Web UI Authentication guide --- docs/user-guides/install.md | 8 +- docs/user-guides/web-ui-authentication.md | 177 ++++++++++++++++++++++ 2 files changed, 181 insertions(+), 4 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/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.