BasicSwap DEX

1. What Is BasicSwap DEX?

BasicSwap is an open‑source, trustless, cross‑chain atomic‑swap decentralized exchange (DEX) created by the Particl community. It combines:

• Order book replicated over the Particl and BitMessage networks.
• HTLC‑based atomic swaps enabling direct BTC ↔ XMR, BTC ↔ PART, LTC ↔ XMR, etc., without custodians or wrapped tokens.
• Privacy & censorship resistance by routing comms over Tor and BitMessage, and by leveraging Particl’s Confidential Transactions for PART trades.

Unlike Bisq (multisig escrow with deposits), BasicSwap relies on hash‑time‑locked contracts; no third‑party mediators or escrow deposits are needed. If a swap participant disappears mid‑process, funds automatically return to the original owners after a timeout. Though it's popularirity is on a downward trend, liquidity is scarce we're not sure if it's just getting started or abandoned.

2. Key Concepts You Should Understand

2.1 Atomic Swaps in a Nutshell

An atomic swap is a two‑transaction protocol:

1. Party A locks Coin X into an HTLC that can be redeemed with secret S (hash pre‑image) within T1 blocks or refunded after.
2. Party B uses the hash of S to lock Coin Y into a second HTLC with shorter timeout T2 (T2 < T1).
3. When B redeems Coin X, they reveal S on‑chain; A uses S to redeem Coin Y.
4. If either side aborts, the refund paths trigger after timeouts.

2.2 BasicSwap Daemon & GUI

• basicswapd — Python service orchestrating wallets, order book sync, and swap negotiations.
• Electron/Qt GUI — optional front‑end that talks to the daemon via JSON‑RPC.

2.3 Supported Chains (July-2025)

2.4 Order Book Distribution

Orders propagate via:

• Particl’s p2p network (OP_RETURN messages)
• BitMessage channels (legacy fallback)
• IPFS (experimental)

No central server, but order discovery can take a few minutes after startup.

3. System Requirements & Prep

Security‑minded? Use a dedicated machine or VPS with encrypted disks. Always run over Tor (built in) or Tailscale exit.

4. Installing BasicSwap

4.1 Quick Start via Docker Compose

git clone https://github.com/particl/basicswap.git && cd basicswap
cp docker/.env.sample .env   # edit RPC usernames/passwords if needed
docker compose up -d

Services started:

• basicswapd (Python)
• Bitcoin Core, Monero monerod, Particl d, Electrum servers (optional)

4.2 Manual (Bare‑Metal) Install

1. Install system deps: git, python3.11, virtualenv, rustup (for some cryptography bindings).
2. Clone repo: git clone https://github.com/particl/basicswap && cd basicswap.
3. Create venv: python -m venv venv && source venv/bin/activate.
4. pip install -r requirements.txt.
5. Copy basicswap.conf.example → basicswap.conf and edit paths to your Bitcoin/Monero/Particl data dirs & RPC creds.
6. Run python basicswap/run.py --init to generate wallet seeds for each chain.

4.3 Verify Binaries & Signatures

Download Core binaries from official projects; verify PGP signatures (Bitcoin Core, Monero).

5. First‑Run Configuration

5.1 Edit basicswap.conf

Key sections:

[BASE]
network = mainnet
listen = 127.0.0.1:12700
use_tor = 1

[bitcoin]
rpc_user = user
rpc_password = pass
rpc_port = 8332
rpc_host = 127.0.0.1

[monero]
rpc_user = foo
rpc_password = bar
rpc_host = 127.0.0.1
rpc_port = 18081

[particl]
...

Enable or disable coins by adding/removing sections.

5.2 Start Nodes

Ensure bitcoind, monerod, particld are syncing. For test‑drive, you can run them in pruned mode:

bitcoind -prune=550

Monero has its own --prune-blockchain flag.

5.3 Launch basicswapd

./basicswap/scripts/start.sh
# or inside venv
python basicswap/run.py

Logs appear in ~/.basicswap/logs/; wait for ORDERBOOK_SYNCED message.

6. Funding Wallets

Each chain wallet is created automatically on first run. Find deposit addresses:

curl -s --user admin:pass http://127.0.0.1:12700/json | jq .
# or use GUI → Wallets tab → Receive

Send a small amount of each asset you plan to swap. Wait for standard confirmations (BTC = 1–3, XMR = 10 blocks, PART = 10).

7. Creating or Taking an Offer

7.1 Take an Existing Offer (Simplest)

1. In GUI: Market tab → choose pair (e.g., BTC/XMR).
2. Review orderbook rows: Amount, Price, Min/Max, Maker fee.
3. Click Take Offer → confirm terms.
4. GUI shows swap progress (6 phases). Do not close the daemon until complete.

7.2 Post a New Offer (Maker)

RPC example:

curl --user admin:pass \
  -d '{"method":"offerscreate","params":{"from":"btc","to":"xmr","amountfrom":0.01,"amountto":1.3,"minswap":0.002,"lockhours":24,"addrto":"48...xmr"}}' \
  http://127.0.0.1:12700/json

• lockhours controls HTLC refund timeout (24 h common; shorter = tighter).
• Offer propagates within ~2 min.

8. Swap Lifecycle Deep Dive

1. Negotiation – Maker & taker exchange public keys, addresses, secret hash.
2. Lock TX 1 – Maker locks coin_from in HTLC.
3. Lock TX 2 – Taker locks coin_to with shorter timeout.
4. Redemption – The party receiving coin_from redeems, revealing secret.
5. Counter‑Redeem – Other side uses secret to redeem coin_to.
6. Done – Both have desired asset; GUI marks swap ✅.
7. Timeout path – If step 3 or 4 fails, refund after lockhours.

9. Fees & Economics

| Fee Type | Paid In | Payer | Typical Amount |
|---|---|---|
| Maker lock TX | chain fee | Maker | On‑chain miner fee. |
| Taker lock TX | chain fee | Taker | Slightly higher (two TXs). |
| Service fee | PART (optional) | Either | 0.25 % default; paid to Particl staking addr. Adjustable → 0. |

Because BasicSwap has no escrow deposits, on‑chain miner fees dominate. Optimize by batching funding UTXOs and watching mempool.

10. Troubleshooting Common Issues

11. Security & Privacy Tips

• Use Tor mode (use_tor = 1) so IP doesn’t appear on offers.
• Set swaptempdir to an encrypted partition; logs may contain TXIDs.
• Separate wallets for swap funds vs HODL cold storage.
• Watch swap progress; if GUI disconnects, leave daemon alive to avoid premature refund conditions.
• Verify HTLC script templates when upgrading versions (regression risk).

12. Upgrading BasicSwap

1. Stop daemon: ./scripts/stop.sh.
2. git pull && docker compose pull (or pip install -U basicswap for venv).
3. Run migrations: python basicswap/run.py --migrate (if prompted).
4. Restart.

Always backup ~/.basicswap/ before major upgrades.

13. Glossary

14. Where to Get Help

• GitHub Issues: https://github.com/particl/basicswap/issues
• Matrix: #basicswapdex:matrix.particl.io
• Docs Wiki: https://academy.particl.io/en/latest/basicswap/
• Telegram relay (unofficial): Search “Particl Chat”.

15. Next Steps

1. Run BasicSwap on testnet first (set [BASE] network = testnet and use tBTC). Familiarize with refund path.
2. Fund mainnet wallets with small amounts and complete a live BTC ↔ XMR swap.
3. Explore scriptless swaps (Schnorr adaptor sig) branch if you’re adventurous.
4. Consider running a public liquidity provider bot to earn spreads.

Happy swapping—and remember: Not your exchange, not your privacy! 🔄🛡️