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 0cb935013de0a0c4ef0b709e86388f9944f890d7 Mon Sep 17 00:00:00 2001 From: cryptoguard Date: Sun, 1 Feb 2026 23:11:00 -0500 Subject: [PATCH 3/3] Add VPS installation / SSH tunneling guide --- docs/user-guides/vps-installation.md | 188 +++++++++++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 docs/user-guides/vps-installation.md diff --git a/docs/user-guides/vps-installation.md b/docs/user-guides/vps-installation.md new file mode 100644 index 0000000..458549f --- /dev/null +++ b/docs/user-guides/vps-installation.md @@ -0,0 +1,188 @@ +--- +sidebar_position: 2 +title: VPS Installation +description: "How to install BasicSwap DEX on a cloud server and access it remotely via SSH tunneling" +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# VPS Installation + +Running BasicSwap on a VPS (Virtual Private Server) lets you keep the DEX online 24/7 without leaving your local machine on. This is particularly useful if you want to use the [market making tool](/docs/user-guides/market-making) to provide liquidity around the clock. + +This guide covers setting up a cloud server, installing BasicSwap on it, and securely accessing the web UI from your local machine through an SSH tunnel. + +## Prerequisites + +- A VPS account with a provider such as Digital Ocean, Vultr, or Hetzner. Digital Ocean is known to work out of the box with no special networking adjustments needed. +- Basic familiarity with the terminal and SSH. + +**Recommended server specs:** + +| Resource | Minimum | +|----------|---------| +| **OS** | Ubuntu 22.04 LTS or newer | +| **RAM** | 8 GB (BasicSwap runs full nodes for each enabled coin) | +| **Storage** | 100 GB+ SSD, depending on which coins you enable | + +:::tip +You can significantly reduce RAM and storage requirements by using [lightweight modes](/docs/user-guides/lightweight-modes) such as Electrum wallets for Bitcoin/Litecoin or remote nodes for Monero. +::: + +## Set Up Your Server + +1. Log in to your cloud provider and create a new server (often called a "droplet" or "instance"). + +2. Select **Ubuntu 22.04 LTS** as the operating system. + +3. Choose a plan with at least **8 GB of RAM** and enough storage for the blockchains of the coins you want to enable. + +4. For authentication, select **SSH key** if possible. Password authentication also works but is less secure. + +5. Deploy the server and note the **IP address** your provider assigns to it. + +## Connect to Your Server + +Open a terminal on your local machine and connect to the server over SSH. + +```bash title="Terminal" +ssh root@YOUR_SERVER_IP +``` + +:::info +The default username depends on your provider. Digital Ocean uses `root`, but others may use `ubuntu` or a different account name. Your provider will tell you which one to use. +::: + +The first time you connect, your terminal will warn you about an unknown host. Type `yes` to accept the host key and continue. Then enter your password (or let your SSH key handle authentication). + +## Prepare the Server + +1. Update all system packages to their latest versions. + +```bash title="Terminal" +sudo apt update && sudo apt upgrade -y +``` + +If prompted about package configuration (for example, which version of OpenSSH to keep), you can safely keep the local version currently installed. + +2. Reboot the server so all updates take effect. + +```bash title="Terminal" +sudo reboot +``` + +3. Wait a moment, then reconnect using the same SSH command. + +```bash title="Terminal" +ssh root@YOUR_SERVER_IP +``` + +:::info +If you get a "Connection refused" error, the server is still rebooting. Wait a bit and try again. +::: + +## Set Up the Firewall + +Before installing BasicSwap, set up a firewall to lock down the server. Since you will access BasicSwap through an SSH tunnel, no additional ports need to be opened. + +```bash title="Terminal" +sudo ufw default deny incoming +sudo ufw default allow outgoing +sudo ufw allow ssh +sudo ufw enable +``` + +Type `y` when asked to confirm. This allows only SSH connections (port 22) and blocks all other incoming traffic. + +:::warning +Make sure you allow SSH **before** enabling the firewall. Otherwise you will lock yourself out of the server. +::: + +## Install BasicSwap + +The Docker installation method is recommended for VPS setups. Follow the **Linux Docker instructions** in the [Installation Guide](/docs/user-guides/install#install-using-docker) to install Docker, create the BasicSwap image, and configure it. + +When you reach the `basicswap-prepare` configuration step, make sure to include these flags: + +- `--htmlhost="0.0.0.0"` and `--wshost="0.0.0.0"` so the web UI is accessible for remote connections. +- `--client-auth-password=YOUR_PASSWORD` to protect the web UI with a password. This is strongly recommended for any network-accessible instance. See the [Web UI Authentication](/docs/user-guides/web-ui-authentication) guide for details. + +Your configuration command should look something like this: + +```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 --client-auth-password=YOUR_PASSWORD +``` + +:::caution +Store the mnemonic seed displayed during setup in a safe place. It is your wallet backup and is valid for all enabled coins. Also note the Monero restore height (`echo $CURRENT_XMR_HEIGHT`) for future recovery. +::: + +## Start BasicSwap + +Navigate to the BasicSwap Docker directory and start the container in detached mode so it keeps running after you close your SSH session. The `COINDATA_PATH` variable is read automatically from the `.env` file you set up during installation. + +```bash title="Terminal" +cd basicswap/docker/ +docker-compose up -d +``` + +## Access BasicSwap From Your Local Machine + +BasicSwap's web UI runs on port 12700. Rather than exposing this port to the internet, use an SSH tunnel to forward it securely to your local machine. + +On your **local machine** (not the server), open a new terminal and run: + +```bash title="Terminal" +ssh -N -L 12700:localhost:12700 root@YOUR_SERVER_IP +``` + +This command forwards port 12700 on your local machine to port 12700 on the server through an encrypted SSH connection. The `-N` flag tells SSH not to execute any remote commands (tunnel only), and `-L` sets up the port forwarding. + +The terminal will appear to hang with no output. This is normal. Keep it open for as long as you want to access the UI. + +Now open your web browser and go to: + +``` +http://localhost:12700 +``` + +You should see the BasicSwap web interface. If you set a password during setup, you will be prompted to log in. + +## Keep BasicSwap Running + +Since you started the container with `docker-compose up -d`, BasicSwap will keep running even after you disconnect from the server. It will also restart automatically if the server reboots, as long as the Docker daemon is enabled (which it is by default on most VPS providers). + +To check that the container is running: + +```bash title="Terminal" +docker ps +``` + +To follow the logs in real time: + +```bash title="Terminal" +cd basicswap/docker/ +docker-compose logs -f +``` + +Press `Ctrl + C` to stop following logs (this does not stop BasicSwap). + +## Security Recommendations + +- **Use SSH key authentication** instead of passwords for your server login. Most VPS providers let you add your public key during server creation. +- **Enable Web UI authentication** with `--client-auth-password` as described above. See the [Web UI Authentication](/docs/user-guides/web-ui-authentication) guide for managing passwords and API access. +- **Keep your server updated** regularly by running `sudo apt update && sudo apt upgrade` and rebooting when needed. +- **Do not expose port 12700** directly to the internet. Always access BasicSwap through an SSH tunnel. + +## Useful Commands + +| Command | Description | +|---------|-------------| +| `docker ps` | Check if BasicSwap is running | +| `docker-compose logs -f` | Follow logs in real time | +| `docker-compose up -d` | Start BasicSwap in the background | +| `docker-compose stop` | Stop BasicSwap | +| `docker-compose restart` | Restart BasicSwap | + +All `docker-compose` commands must be run from the `basicswap/docker/` directory.