Git-Mirrors/xmr-btc-swap
1
0
Fork 0
mirror of https://github.com/comit-network/xmr-btc-swap.git synced 2025-12-17 17:44:02 -05:00
Code Issues Projects Releases Packages Wiki Activity

docs: clarify orchestrator restart instructions (#581)

Browse source
This commit is contained in:
Mohan 2025-09-25 02:20:09 +02:00 • committed by GitHub
parent 60c59aa542
commit 114696430e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 71 additions and 70 deletions
Download patch file Download diff file Expand all files Collapse all files

49
dev-docs/asb/README.md
View file

@ -2,28 +2,25 @@
## Quick Start
From version `0.6.0` onwards the software default to running on `mainnet`.
It is recommended to try the software on testnet first, which can be achieved by providing the `--testnet` flag.
This quickstart guide assumes that you are running the software on testnet (i.e. Bitcoin testnet3 and Monero stagenet):
The recommended way to operate an ASB is through the `orchestrator` tool that ships with this repository.
The orchestrator generates a hardened Docker Compose environment that runs the ASB together with dedicated Bitcoin and Monero infrastructure.
Refer to the [orchestrator README](https://github.com/eigenwallet/core/blob/main/swap-orchestrator/README.md) for a full command reference, architecture overview, and automation tips.
1. Download [latest release](https://github.com/comit-network/xmr-btc-swap/releases/latest) of the `asb` binary
2. Ensure that you have the Monero Wallet RPC running with `--wallet-dir` and `--disable-rpc-login`:
1. `monero-wallet-rpc --stagenet --daemon-host STAGENET-NODE-URL --rpc-bind-port STAGENET-NODE-PORT --disable-rpc-login --wallet-dir PATH/TO/WALLET/DIR`
3. Run the ASB in terminal: `./asb --testnet start`
4. Follow the setup wizard in the terminal
1. Install [Docker](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/) on the machine that will host your maker.
2. Download the latest [orchestrator release](https://github.com/eigenwallet/core/releases) (or build it from source) and make the binary executable.
3. Create an empty working directory, place the binary inside and start the wizard: `./orchestrator`.
4. Pick the networks you want to operate on (mainnet or the Bitcoin testnet/Monero stagenet pair) and answer the prompts about ports, Tor settings and maker parameters.
5. Once the wizard finishes run `docker compose up -d --build` from the same directory to start the environment.
6. Attach to the ASB control shell with `docker compose attach asb-controller` and type `help` to inspect available commands.
The README includes additional controller examples if you need to script JSON-RPC calls.
Public Monero nodes for running the Monero Wallet RPC on stagenet can be found [here](https://monero.fail/?chain=monero). Public Electrum nodes for testnet can be found [here](https://1209k.com/bitcoin-eye/ele.php?chain=tbtc).
The generated `config.toml` lives next to `docker-compose.yml`. Edit it to adjust maker parameters, then restart the ASB container with `docker compose restart asb` to apply the changes.
Run `./asb --help` for more information.
### Running on mainnet vs. testnet
### Running on mainnet
The orchestrator allows you to select the networks during the wizard. Choose Bitcoin testnet & Monero stagenet for a dry run, or Bitcoin mainnet & Monero mainnet for production.
For running the ASB on mainnet you will have to change you `monero-wallet-rpc` setup to mainnet.
It is recommended that you run your own Monero and Bitcoin node when running on mainnet.
It is possible to plug into public blockchain nodes but be aware that you might lose some privacy doing so.
Public Monero mainnet nodes can be found [here](https://monero.fail/?chain=monero).
Public Electrum mainnet nodes can be found [here](https://1209k.com/bitcoin-eye/ele.php?chain=btc).
If you run on mainnet we strongly recommend keeping the default self-hosted nodes that the orchestrator provisions. They provide better privacy than connecting to third-party RPC servers.
### Connect with others
@ -31,9 +28,9 @@ Consider joining the designated [Matrix chat](https://matrix.to/#/%23unstoppable
### Using Docker
Running the ASB and its required services (Bitcoin node, Monero node, wallet RPC) can be complex to set up manually.
We provide a Docker Compose solution that handles all of this automatically.
See our [docker-compose repository](https://github.com/eigenwallet/asb-docker-compose) for setup instructions and configuration details.
The orchestrator manages the Docker Compose setup for you.
Re-run `./orchestrator` whenever you want to regenerate the compose file with new container images or port assignments—the tool preserves your `config.toml` and Docker volumes.
Day-to-day operations happen via `docker compose` from the orchestrator directory (`up`, `down`, `logs`, `ps`, etc.).
## ASB Details
@ -95,14 +92,10 @@ The `ASB` depicted in the diagram actually consists of multiple components (prot
#### Monero Wallet Setup
The ASB uses the running Monero wallet RPC to create / open Monero wallets.
Currently you cannot connect to an existing Monero wallet, but the ASB will create the wallet `asb-wallet` upon intial startup.
In order to accept trades with a CLI you will have to send XMR to that wallet.
The wallet's address is printed upon startup of the ASB.
Currently the `asb-wallet` does not have a password.
Upon startup of the ASB the `asb-wallet` is opened in the wallet RPC.
You can then interact with the wallet RPC for basic wallet management as well.
The ASB manages Monero wallets internally through direct FFI bindings and stores them inside the Docker volume mounted at `/asb-data`.
On first start it creates a wallet and prints the primary address in the logs.
Fund that wallet with enough XMR liquidity to cover the swaps you intend to make.
You can export the wallet seed (and restore height) via the controller's `monero-seed` command when you need to recover it in another wallet application.
#### Bitcoin Wallet Setup

92
docs/pages/becoming_a_maker/overview.mdx
View file

@ -10,85 +10,93 @@ For this, it uses direct FFI wallet access via `monero-sys` for Monero and `elec
It's also strongly recommended to run your own Monero and Bitcoin nodes.
## Docker Compose setup
## Orchestrator setup
We maintain a Docker Compose configuration ([link](https://github.com/eigenwallet/asb-docker-compose)) that automatically starts and manages these services:
We ship an `orchestrator` binary that builds a production ready Docker Compose environment for the ASB.
The orchestrator walks you through a wizard, creates the ASB configuration and pins a Docker Compose file with all required services:
- `asb` (the maker service, with built-in wallet functionality connecting directly to `monerod` and `electrs`)
- `electrs` (a Bitcoin blockchain indexer, connecting to `bitcoind`)
- `monerod` (a Monero node, connecting to the Monero blockchain)
- `bitcoind` (a Bitcoin node, connecting to the Bitcoin blockchain)
- `asb-controller` (a REPL for issuing JSON-RPC commands to the ASB)
- `asb-tracing-logger` (high verbosity ASB logs)
- `electrs` (Bitcoin blockchain indexer, connecting to `bitcoind`)
- `monerod` (Monero node)
- `bitcoind` (Bitcoin node)
To run this setup you'll need Docker and Docker Compose installed.
### Getting started
Now you can clone the configuration repo and `cd` into it.
We're going to setup an asb on mainnet.
If you want to setup for testnet, go into the `testnet` directory instead.
All other steps remain the same.
Download the latest [orchestrator release](https://github.com/eigenwallet/core/releases) for your platform (or build it from source) and make it executable.
If you're on Linux x86_64 you can use the quick install snippet documented in the [orchestrator README](https://github.com/eigenwallet/core/blob/main/swap-orchestrator/README.md#quick-install) to fetch the newest binary.
Place the binary in an empty directory and run the wizard:
```bash
git clone https://github.com/eigenwallet/asb-docker-compose.git
cd asb-docker-compose/mainnet
./orchestrator
```
The directory contains three files: the docker compose file, the enviroment variables file and the asb configuration file.
The directory structure looks like this:
```bash
asb-docker-compose/mainnet/
├─ config_mainnet.toml # asb configuration
├─ docker-compose.yml # docker compose configuration
├─ .env # port configuration for docker compose
```
The `docker-compose.yml` and `.env` files are part of the docker compose setup.
We will prioritize the asb configuration file in this guide, because you probably don't want to change the docker compose setup.
Answer the prompts to configure the Bitcoin/Monero networks, exposed ports and ASB options.
When the wizard finishes you'll have a `docker-compose.yml`, a matching `config.toml`, and Docker volumes ready to store blockchain data and ASB state.
The README also covers the generated directory layout and additional management commands if you want to dive deeper into the tool's capabilities.
### Usage and commands
_This list is also available in the [repository](https://github.com/eigenwallet/asb-docker-compose/), including variations for testnet._
First, make sure you're in the directory with the `docker-compose.yml` file:
All Docker commands below are executed from the directory that contains the generated `docker-compose.yml` file:
```bash copy
cd asb-docker-compose/mainnet
cd /path/to/orchestrator-output
```
If you aren't familiar with docker compose, here are the most important commands:
| Command | Description |
| --- | --- |
| `docker compose up -d` | Start all services. |
| `docker compose up -d --build` | Build images (if requested) and start all services. |
| `docker compose up -d` | Start all services using the existing images. |
| `docker compose down` | Stop all services. |
| `docker compose ps` | List all currently running services. |
| `docker compose pull` | Pull the latest images for all services. You need to run `docker compose up -d` after this to actually update the services. |
| `docker compose logs -f` | Access the logs of all services. To only get the logs of a specific service, use `docker compose logs -f <service_name>`. To only see the last e.g. 100 lines, use `docker compose logs -f --tail 100`. |
| `docker compose logs -f --tail 100` | Follow logs for all services. Append a service name (for example `asb` or `asb-tracing-logger`) to scope the output. |
You can also execute `asb` commands, to get the history of swaps for example:
Once `docker compose up` reports the containers as healthy you can attach to the ASB controller shell:
```bash copy
docker compose exec mainnet_asb asb --config=/asb-data/config_mainnet.toml history
docker compose attach asb-controller
```
Below is a list of asb commands you can use.
Some of them require access to some resources, in which case you'll need to stop the asb first and then resume afterwards:
The controller exposes commands such as `bitcoin-balance`, `monero-balance`, `monero-address`, `multiaddresses`, and `get-swaps`.
Type `help` inside the shell to see the full list. Use `quit` to exit the REPL when you're done.
For more verbose ASB logs, stream the `asb-tracing-logger` output:
```bash copy
docker compose logs -f --tail 100 asb-tracing-logger
```
### Running `asb` commands directly
Some maintenance tasks still require invoking the `asb` binary instead of going through the JSON-RPC controller. The orchestrator mounts your configuration file at `/asb-data/config.toml` inside the container, so you can execute commands like `history` or `export-bitcoin-wallet` straight from the host:
```bash copy
docker compose exec asb asb --config=/asb-data/config.toml history
```
If you generated a testnet/stagenet environment, include the `--testnet` flag right after the binary name:
```bash copy
docker compose exec asb asb --testnet --config=/asb-data/config.toml history
```
Commands that modify internal wallets (for example `withdraw-btc` or `export-bitcoin-wallet`) work the same way—just replace `history` with the subcommand you need.
If you need to stop the environment temporarily:
```bash copy
docker compose down
docker compose exec mainnet_asb asb --config=/asb-data/config_mainnet.toml <command>
docker compose up -d
```
| Command | Description |
| --- | --- |
| `help` | Prints a list of available options and commands (under _subcommands_). |
| `history` | Prints a list of all previous and current swaps. |
| `start` | Starts the asb. This is automatically done when you run `docker compose up -d`. |
| `config` | Prints the current configuration. |
| `export-bitcoin-wallet` | Prints the internal bitcoin wallet descriptor which can be used to access the asb's bitcoin wallet. |
| `withdraw-btc --address <YOUR_ADDRESS>` | Withdraws Bitcoin from the internal wallet into a specified address. |
The ASB configuration lives in `config.toml` next to the compose file. You can edit it between runs and reapply the changes by restarting the ASB container (`docker compose restart asb`).
### Asb Configuration