From 6b88ba516340d70850b61bb9f91190eff5997a02 Mon Sep 17 00:00:00 2001 From: h4sh3d Date: Wed, 10 Aug 2022 11:24:39 +0200 Subject: [PATCH 1/2] doc: move documentation to wiki --- README.md | 196 +++---------------------------------------- doc/README.md | 3 - doc/docker-stack.md | 139 ------------------------------ doc/install-guide.md | 98 ---------------------- doc/local-swap.md | 135 ----------------------------- 5 files changed, 10 insertions(+), 561 deletions(-) delete mode 100644 doc/docker-stack.md delete mode 100644 doc/install-guide.md delete mode 100644 doc/local-swap.md diff --git a/README.md b/README.md index 36ccecdb7..cd66e1f59 100644 --- a/README.md +++ b/README.md @@ -11,198 +11,22 @@ The **Farcaster Node** is _a collection of microservices for running cross-chain Microservices currently implemented: -- farcasterd (1 instance): the swap manager, it is aware of every initiated swap and interconnects all the other microservices, launches and kills other microservices, exposes an API for the swap-cli client -- swapd (1 instance per swap): control centre for an individual swap -- keeps track of the swap's state as it runs the protocol's state machine, and orchestrates the swap with peerd for communicating with swap counterparty, walletd for signing, and syncers for blockchain interactions. -- walletd (1 instance): where secret keys live, where transactions are signed, coordinates with swapd -- swap-cli: stateless terminal client (=executes a single command and terminates) that commands farcasterd, for taking or making offers, for example -- peerd (1 instance per peer connection): handles the connection to an individual peer, -- syncerd (1 instance per blockchain, i.e. one for monero and one for bitcoin): interface for getting updates of the blockchain and for broadcasting transactions +- **farcasterd** (1 instance): the swap manager, it is aware of every initiated swap and interconnects all the other microservices, launches and kills other microservices, exposes an API for the swap-cli client +- **swapd** (1 instance per swap): control centre for an individual swap -- keeps track of the swap's state as it runs the protocol's state machine, and orchestrates the swap with peerd for communicating with swap counterparty, walletd for signing, and syncers for blockchain interactions. +- **walletd** (1 instance): where secret keys live, where transactions are signed, coordinates with swapd +- **swap-cli** stateless terminal client (=executes a single command and terminates) that commands farcasterd, for taking or making offers, for example +- **peerd** (1 instance per peer connection): handles the connection to an individual peer, +- **syncerd** (1 instance per blockchain, i.e. one for monero and one for bitcoin): interface for getting updates of the blockchain and for broadcasting transactions +- **databased** (1 instance): interface for storing data persistently across restart +- **grpcd** (1 instance): interface for exposing node interfaces as a gRPC endpoint Farcaster Node is build on atomic swap primitives described in the [RFCs](https://github.com/farcaster-project/RFCs) and implemented in [Farcaster Core](https://github.com/farcaster-project/farcaster-core). :information_source: This work is based on LNP/BP work, this project is a fork from [LNP-BP/lnp-node](https://github.com/LNP-BP/lnp-node) since [acbb4c](https://github.com/farcaster-project/farcaster-node/commit/acbb4c467695dc3d1c02b88be97e9a6e2d434435). -## Build and run +## Documentation -Follow the instruction for [`installing the node`](./doc/install-guide.md) on your machine by compiling sources or using containers. Containers might be your best bet, for a quick try. - -Depending on the chosen installation method: - -- you now have to continue to [build from sources](#build-from-sources) -- or continue to [run with docker](#run-with-docker) - -They provide instructions on how to launch the swap node, codenamed `farcasterd`. - -### Build from sources - -If you installed the node on your machine from sources (i.e. not using Docker) you can now launch the services needed for the swap. - -#### Launching Monero RPC wallet - -First you need to run a `monero rpc wallet` to manage the moneros, if you have it already installed on your machine you can run - -``` -monero-wallet-rpc --stagenet --rpc-bind-port 38083\ - --disable-rpc-login\ - --daemon-host stagenet.community.rino.io:38081\ - --trusted-daemon\ - --password "soMeDummYPasSwOrd"\ - --wallet-dir ~/.fc_monero_wallets -``` - -or you can use the Docker image - -``` -docker run --rm -p 38083:38083 ghcr.io/farcaster-project/containers/monero-wallet-rpc:latest\ - /usr/bin/monero-wallet-rpc --stagenet\ - --disable-rpc-login --wallet-dir wallets\ - --daemon-host stagenet.community.rino.io:38081\ - --rpc-bind-ip 0.0.0.0 --rpc-bind-port 38083\ - --confirm-external-bind -``` - -#### Launching `farcasterd` - -Now that you have a working Monero RPC wallet to connect you can launch the node, and follow the logs to see what's appening. - -``` -farcasterd -``` - -:mag_right: You can find more details below about the [configuration](#configuration) if you need to customize some values. - -#### Connect a client - -Once `farcasterd` is up & running you can issue commands to control its actions with a client. For the time being, only one client is provided within this repo: `swap-cli`. - -If you launched `farcasterd` with the default paramters (the `--data-dir` argument or `-d`), `swap-cli` will be able to connect to `farcasterd` without further configuration. You can get informations about the node with - -``` -swap-cli info -``` - -Run `help` command for more details about available commands. - -Commands you should know: `swap-cli info` gives a genaral overview of the node, `swap-cli ls` lists the ongoing swaps and `swap-cli progress ` give the state of a given swap. - -With those commands and farcasterd logs you should be able to follow your swaps. - -Checkout the documentaion on [how to use the node](#usage) to learn how to make and take offers. - -### Run with docker - -If you did use Docker you are already all set up. Run `docker-compose up -d` if you haven't yet, and the node and the wallet will start running. You can interact with `farcasterd` container using the cli via - -``` -docker-compose exec farcasterd swap-cli info -``` - -Commands you should know: `swap-cli info` gives a genaral overview of the node, `swap-cli ls` lists the ongoing swaps and `swap-cli progress ` gives the state of a given swap. - -With those commands and farcasterd logs (attach to the log with `docker-compose logs -f --no-log-prefix farcasterd`), you should be able to follow your swaps. - -Check out the documentation on [configuration](#configuration) for more advanced setups. - -## Usage - -:rotating_light: **The following section focus on how to use the Farcaster Node to propose and run atomic swaps. Keep in mind that this software remains experimental and should not be used on mainnet or with real money.** - -When `farcasterd` is up & running and `swap-cli` is configured to connect and control it, you can make offers and/or take offers. An offer encapsulate informations about a trade of Bitcoin and Monero. One will make :hammer: an offer, e.g. a market maker, and one will try to take :moneybag: the offer. Below are the commands to use to either `make` an offer or `take` one. - -If you just want to take a public offer, you may jump to [Take the offer](#:moneybag:-take-the-offer). - -### :hammer: Make an offer - -After making an offer, the maker starts listening for other peers to connect and take that offer -- and hopefully execute a swap successfully. - -A `peerd` instance is spawned by the maker and binds to the specified `address:port`. The taker's `farcasterd` then launches its own `peerd` that connects to the makers `peerd`. The communication is then established between two nodes, and they can pass lightning encoded peer messages and swap. - -:mag_right: This requires for the time being some notions about the network topology the maker node is running in; this requirement will be removed once we're integrating Tor by default. - -If you are the maker, to make an offer and spawn a listener awaiting for takers to take that offer, run the following command: - -``` -swap-cli make --btc-addr tb1q935eq5fl2a3ajpqp0e3d7z36g7vctcgv05f5lf\ - --xmr-addr 54EYTy2HYFcAXwAbFQ3HmAis8JLNmxRdTC9DwQL7sGJd4CAUYimPxuQHYkMNg1EELNP85YqFwqraLd4ovz6UeeekFLoCKiu\ - --btc-amount "0.0000135 BTC" --xmr-amount "0.001 XMR"\ - --network testnet --arb-blockchain bitcoin --acc-blockchain monero\ - --maker-role Bob --cancel-timelock 4 --punish-timelock 5 --fee-strategy "1 satoshi/vByte"\ - --public-ip-addr 1.2.3.4 --bind-ip-addr 0.0.0.0 --port 9735 -``` - -The `btc-addr` and `xmr-addr` are your external wallet addresses, where the coins will end up upon successful or failure cases. They are followed by the amounts exchanged. Assets and networks defaults to Bitcoin and Monero on testnet (Bitcoin testnet3, Monero stagenet). - -The role for the maker is specified in the offer with `--maker-role`. `Alice` sells moneroj for bitcoins, `Bob` sells bitcoins for moneroj. Timelock parameters are set to **4** and **5** for cancel and punish and the transaction fee that must be applied is **1 satoshi per vByte**. - -Here the maker will send bitcoins and will receive moneroj in her `54EYTy2HYFcAXwAbFQ3HmAis8JLNmxRdTC9DwQL7sGJd4CAUYimPxuQHYkMNg1EELNP85YqFwqraLd4ovz6UeeekFLoCKiu` address if the swap is successful. - -`--public-ip-addr` (default to `127.0.0.1`) and `--port` (default to `9735`) are used in the public offer for the taker to connect. `--bind-ip-addr` allows to bind the listening peerd to `0.0.0.0`. - -:mag_right: To enable a taker to connect and take the offer the `public-ip-addr:port` must be accessible and answered by the `peerd` bound to `bind-id-address:port`. - -So maker must make sure her router allows external connections to that port to her node. - -**The public offer result** - -The make command will output an encoded **public offer** that can be shared with potential takers. As a maker, your `farcasterd` registers this public offer, and waits for someone to connect through `peerd` and take the offer. A taker in her turn takes the offer and initiates a swap with the maker. - -Follow your `farcasterd` logs (**you can fine tune your log with `RUST_LOG` environment variable, e.g. `RUST_LOG="farcaster_node=debug,microservices=debug"`**) and fund the swap with the bitcoins or moneros when the log asks for this. At the end coins are swapped successfully, or - less ideally - refunded. We currently offer no manual cancel functionality. We offer progress through `swap-cli progress {swapid}`. To list the the swapids of the running swaps, use `swap-cli ls`. - -### :moneybag: Take the offer - -Taking a public offer is a much simpler process: all you need is a running node (doesn't require to know your network topology), an encoded public offer, a Bitcoin address and a Monero address to receive assets, again as a refund or as a payment depending on your swap role and if the swap completes. - -``` -swap-cli take --btc-addr tb1qmcku4ht3tq53tvdl5hj03rajpdkdatd4w4mswx\ - --xmr-addr 54EYTy2HYFcAXwAbFQ3HmAis8JLNmxRdTC9DwQL7sGJd4CAUYimPxuQHYkMNg1EELNP85YqFwqraLd4ovz6UeeekFLoCKiu\ - --offer {offer} -``` - -The cli will ask you to validate the offer's specifics (amounts, assets, etc.). You can use the flag of interest `--without-validation` or `-w` for externally validated automated setups. - -Then follow your `farcasterd` logs and fund the swap with the bitcoins or moneroj when it asks so. At the end of the swap, you should receive the counterparty's assets. - -### Configuration - -`farcasterd` can be configured through a `.toml` file located by default at `~/.farcaster/farcasterd.toml` (for Linux and BSD, macOS will use `/Users/{user}/Library/Application Support/Farcaster/` and see [here](./src/opts.rs) for more platforms specific). If no file is found, `farcasterd` is launched with some default values. You can see an example [here](./farcasterd.toml). - -**Syncers** - -This entry configures the daemons' connection URLs for the three possible networks: _mainnet_, _testnet_, _local_: - -```toml -[syncers.{network}] -electrum_server = "" -monero_daemon = "" -monero_rpc_wallet = "" -``` - -:mag_right: The default config for _local_ network is set to `null`. - -#### :bulb: Use public infrastructure - -To help quickly test and avoid running the entire infrastructure on your machine, you can make use of public nodes. Following is a non-exhaustive list of public nodes. - -Only blockchain daemons and electrum servers are listed, you should always run your own `monero rpc wallet`. - -**Mainnet** - -| daemon | value | -| ----------------- | ---------------------------------------------------- | -| `electrum server` | `ssl://blockstream.info:700` **(default)** | -| `monero daemon` | `http://node.community.rino.io:18081` | -| `monero daemon` | `http://node.monerooutreach.org:18081` **(default)** | - -**Testnet/Stagenet** - -| daemon | value | -| ----------------- | ------------------------------------------------------- | -| `electrum server` | `ssl://blockstream.info:993` **(default)** | -| `monero daemon` | `http://stagenet.community.rino.io:38081` **(default)** | - -### Run a swap locally - -If you want to test a swap with yourself locally, you can follow the instructions [here](./doc/local-swap.md). +Checkout Farcaster documentation in the [wiki](https://github.com/farcaster-project/farcaster-node/wiki). ## Releases and Changelog diff --git a/doc/README.md b/doc/README.md index f0ceeee80..0fbbfe5e6 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,7 +1,4 @@ # Farcaster Node Documentation -- [`installation guide`](./install-guide.md) describe how to install Farcaster locally. -- [`run a swap locally`](./local-swap.md) describe how to run a swap with both participant locally. -- [`docker stack`](./docker-stack.md) documents how to use the node with docker and docker compose. - [`sequence diagram`](./sequencediagram.txt) of message flow between services ([sequencediagram.org](https://sequencediagram.org/)). - [`state machine`](./swap_state_machine.txt) shows the states and transition messages of swapd ([edotor.net](https://edotor.net/)). diff --git a/doc/docker-stack.md b/doc/docker-stack.md deleted file mode 100644 index 896ef3e61..000000000 --- a/doc/docker-stack.md +++ /dev/null @@ -1,139 +0,0 @@ -# How to use `farcasterd` with Docker - -This project provide some docker images and a docker compose setup to help running the node locally with less efforts. Before reading further make sure docker and docker compose are installed on your machine. - -## Docker compose - -To launch `farcasterd` on your machine clone this project and run: - -``` -docker pull ghcr.io/farcaster-project/farcaster-node/farcasterd:latest -docker-compose up -d -docker-compose logs -f --no-log-prefix farcasterd -``` - -:mega: Don't forget to pull images to ensure you are running the lastest version! - -These commands launch a local Monero Wallet RPC and the Farcaster node, then follow the logs produced by `farcasterd`. Daemons used by the services are public testnet servers. - -Install `swap-cli` on your machine (follow the documentation on [build and run locally](../README.md#locally)) and run: - -``` -swap-cli -x "lnpz://127.0.0.1:9981/?api=esb" info -``` - -For ease of use you can also create an alias: - -``` -alias swap='swap-cli -x "lnpz://127.0.0.1:9981/?api=esb"' -swap info -``` - -You should get a returned value from the node. You can use this stack to take a public offer or to make an offer. In the case you want to make an offer make sure the public address and the port will be reachable from external networks. - -:mega: The only port forwarded to the host is `9735`, make sure to use this one when making offers (by default port `9735` is used). - -To stop and remove the containers simply run in the project folder: - -``` -docker-compose down -``` - -### Images used - -Images used in the docker compose are produced by the `farcaster-project` directly. - -| Service | Image | -| ------------ | ----------------------------------------------------------------- | -| `farcasterd` | `ghcr.io/farcaster-project/farcaster-node/farcasterd:latest` | -| `walletrpc` | `ghcr.io/farcaster-project/containers/monero-wallet-rpc:0.18.0.0` | - -## Docker image - -You can use the docker image directly with: - -``` -docker run --rm --init -t -p 9735:9735 -p 9981:9981\ - --mount type=bind,source=,destination=/etc/farcaster\ - --name farcaster_node\ - ghcr.io/farcaster-project/farcaster-node/farcasterd:latest\ - -c /etc/farcaster/farcasterd.toml -``` - -If you don't use the default values for syncers daemons don't forget to mount your config inside the container (here at `/etc/farcaster`) and pass the config file with `-c /etc/farcaster/farcasterd.toml`. - -or build the node image and start a container by running inside the project folder: - -``` -docker build --no-cache -t farcasterd:latest . -docker run --rm -t --init -p 9735:9735 -p 9981:9981\ - --mount type=bind,source=,destination=/etc/farcaster\ - --name farcaster_node\ - farcasterd:latest\ - {farcasterd args...} -``` - -The container will be removed after execution (`--rm`), allocate a pseudo-TTY (`-t`), and publish exposed ports `9735` and `9981` on the host. - -Stop the container with `ctrl+c` or `docker stop farcaster_node`. - -:warning: this exposes the control bus on the host, only intended for debugging or on a trusted network. - -## Run `monero rpc wallet` - -:mega: No monero are stored long-term in this wallet, the wallet is only used to detect locking and sweep to the specified external Monero address given in parameter at the beginning of the swap! Data needed to create this Monero wallet are managed by farcaster. - -You need to run a Monero wallet RPC server locally to manage receiving and transfering moneros during a swap. You can run your own wallet RPC or use the following commands to create a temporary wallet RPC with one of our Docker image: - -``` -docker pull ghcr.io/farcaster-project/containers/monero-wallet-rpc:latest -docker run --rm -p 38083:38083 ghcr.io/farcaster-project/containers/monero-wallet-rpc:latest\ - /usr/bin/monero-wallet-rpc --stagenet\ - --disable-rpc-login --wallet-dir wallets\ - --daemon-host stagenet.community.rino.io:38081\ - --rpc-bind-ip 0.0.0.0 --rpc-bind-port 38083\ - --confirm-external-bind -``` - -Then use the following values in `farcasterd` configuration file: - -| `monero_rpc_wallet` | value | -| ------------------- | ------------------------ | -| mainnet | `http://localhost:18083` | -| stagenet | `http://localhost:38083` | - -Remove `--stagenet` add change `--rpc-bind-port` and `-p` values to `18083` and connect to a **mainnet** daemon host, see [:bulb: Use public infrastructure](../README.md#bulb-use-public-infrastructure) for public mainnet daemon hosts. - -## Connect a client - -To connect a client and command `farcasterd` running inside a Docker container simply run: - -``` -swap-cli -x "lnpz://127.0.0.1:9981/?api=esb" info -``` - -This configure the cli to connects to the exposed port `9981` of the running container `farcasterd`. - -### Remote client usage - -Example from using other URLs supported by crate `internet2` `node_addr.rs`, besides the default inter process communication (also used by the Docker image to expose the control bus). - -The daemon is controlled though ZMQ _ctl_ socket, an internal interface for control PRC protocol communications. Another ZMQ socket is used to forward all incoming protocol messages, the _msg_ socket. Both are node internal communication channels. Message from counterparty come through `peerd` services. - -**Farcasterd** - -To launch `farcasterd` with network binded _control_ (`-x`) bus and _message_ bus (`-m`) instead of `ctl.rpc` and `msg.rpc` files: - -``` -farcasterd -x "lnpz://127.0.0.1:9981/?api=esb" -m "lnpz://127.0.0.1:9982/?api=esb" -``` - -**Client** - -The following client can instruct the above `farcasterd` to return general informations as follows (client uses the control bus to commuicate with `farcasterd`): - -``` -swap-cli -x "lnpz://127.0.0.1:9981/?api=esb" info -``` - -:mega: It is worth noting that _ctl_ and _msg_ sockets can use different type of communication. E.g. the docker stack only binds the _ctl_ socket over the network and keeps the _msg_ to its default `msg.rpc` file inside the data directory. diff --git a/doc/install-guide.md b/doc/install-guide.md deleted file mode 100644 index 6693cdad1..000000000 --- a/doc/install-guide.md +++ /dev/null @@ -1,98 +0,0 @@ -# Installation Guide - -We provide two methods to install Farcater: compiling the software from [sources](#install-from-sources) or using [containers](#with-docker-and-docker-compose). - -To install Farcaster on your machine from sources you need some terminal knowledge and know how to use your package manager. - -## Install from sources - -After instaling [Rust](https://www.rust-lang.org/tools/install) don't forget to run `source $HOME/.cargo/env` or start a new terminal session. The binaries will be installed in `$HOME/.cargo/bin`. - -### Ubuntu & Debian 10/11 - -To install Farcaster on Debian Buster or Bullseye run the following commands. - -Install dependencies - -``` -apt-get update -y -apt-get install -y git curl libssl-dev pkg-config build-essential cmake -``` - -Install Rust - -``` -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -source $HOME/.cargo/env -``` - -Clone and build the project - -``` -git clone https://github.com/farcaster-project/farcaster-node.git && cd farcaster-node -cargo install --path . --bins --all-features --locked -``` - -### Archlinux - -Install Rust - -``` -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -source $HOME/.cargo/env -``` - -Install dependencies - -``` -pacman -Syy && pacman -Syu -pacman -Sy git base-devel cmake -``` - -Clone and build the project - -``` -git clone https://github.com/farcaster-project/farcaster-node.git && cd farcaster-node -cargo install --path . --bins --all-features --locked -``` - -### macOS 11/12 - -Install [Homebrew](https://brew.sh/) and [Rust](https://www.rust-lang.org/tools/install), then install the dependencies - -``` -brew install cmake -``` - -Clone and build the project - -``` -git clone https://github.com/farcaster-project/farcaster-node.git && cd farcaster-node -cargo install --path . --bins --all-features --locked -``` - -## With Docker and Docker Compose - -You can use the Docker image [`farcasterd`](https://github.com/farcaster-project/farcaster-node/pkgs/container/farcaster-node%2Ffarcasterd) and images from the [`containers`](https://github.com/orgs/farcaster-project/packages?repo_name=containers) repo. - -The easiet way is to use Docker compose to run both the node and the Monero wallet. Copy and paste the following in a `docker-compose.yml` file and run `docker-compose up -d` - -```yaml -version: "3.9" -services: - farcasterd: - image: "ghcr.io/farcaster-project/farcaster-node/farcasterd:compose" - container_name: farcasterd - ports: - - "9735:9735" - - "9981:9981" - command: "-c /var/lib/farcaster/farcasterd.toml" - depends_on: - - "walletrpc" - walletrpc: - image: "ghcr.io/farcaster-project/containers/monero-wallet-rpc:0.18.0.0" - container_name: walletrpc - command: "/usr/bin/monero-wallet-rpc --stagenet --disable-rpc-login --wallet-dir wallets --daemon-host stagenet.community.rino.io:38081 --rpc-bind-ip 0.0.0.0 --rpc-bind-port 38083 --confirm-external-bind" -``` - -:mag_right: If you plan to make offer with the Docker stack make sure you understand what ports need to be open and forwarded. You might need to additionally configure your firewall to enable takers to connect. diff --git a/doc/local-swap.md b/doc/local-swap.md deleted file mode 100644 index 8ca04b179..000000000 --- a/doc/local-swap.md +++ /dev/null @@ -1,135 +0,0 @@ -# Run a swap locally - -This document describe how to test a swap running both participant locally. - -You'll need to build and install the node locally as described [here](../README.md#locally). - -We'll create two node instances and will make them running a swap, for that make sure to have access to the three services: an `electrum server`, a `monero daemon`, and a `monero rpc wallet`. - -## Run `monero rpc wallet` with Docker - -:warning: You should run two containers, one for each `farcasterd` services, choose different ports and modify `--rpc-bind-port` and `-p` values accordingly. Pull the latest image and launch two containers: - -``` -docker pull ghcr.io/farcaster-project/containers/monero-wallet-rpc:latest -docker run --rm -p 38083:38083 ghcr.io/farcaster-project/containers/monero-wallet-rpc:latest\ - /usr/bin/monero-wallet-rpc --stagenet\ - --disable-rpc-login --wallet-dir wallets\ - --daemon-host stagenet.community.rino.io:38081\ - --rpc-bind-ip 0.0.0.0 --rpc-bind-port 38083\ - --confirm-external-bind -``` - -and - -``` -docker run --rm -p 38084:38084 ghcr.io/farcaster-project/containers/monero-wallet-rpc:latest\ - /usr/bin/monero-wallet-rpc --stagenet\ - --disable-rpc-login --wallet-dir wallets\ - --daemon-host stagenet.community.rino.io:38081\ - --rpc-bind-ip 0.0.0.0 --rpc-bind-port 38084\ - --confirm-external-bind -``` - -See [run `monero rpc wallet`](./docker-stack.md#run-monero-rpc-wallet) with Docker for more details. - -## Launch `farcasterd` services - -We will start two daemons with different data directories (`.node01` and `.node02`). First configure both node (with config files `.node01/farcasterd.toml` and `.node02/farcasterd.toml`) to use the two different monero rpc wallets you previously started and change the port for `monero_rpc_wallet` accordingly: - -```toml -[syncers.testnet] -electrum_server = "ssl://blockstream.info:993" -monero_daemon = "http://stagenet.community.rino.io:38081" -monero_rpc_wallet = "http://localhost:{38083|38084}" -``` - -Then launch two `farcasterd` services: - -``` -farcasterd --data-dir {.node01|.node02} -``` - -You can use other public daemons for syncers, see [:bulb: Use public infrastructure](../README.md#bulb-use-public-infrastructure) for more details. - -## Configure `swap-cli` clients - -For simplicity you can create two aliases for the `swap-cli`, you will use them to make and take offers: - -``` -alias swap1-cli="swap-cli -d .node01" -alias swap2-cli="swap-cli -d .node02" -``` - -## Access to assets - -You need to have access to Bitcoin (testnet) and Monero (stagenet) test coins, use your wallet of choice. You just need a way to fund the swap in bitcoins and moneros. - -## Make the offer - -Maker creates offer and start listening. Command used to print a serialized representation of the offer that shall be shared with taker. Additionally it spins up the listener awaiting for connection related to this offer (bound on `0.0.0.0:9735` by default, with an offer public address of `127.0.0.1:9735` by default). - -``` -swap1-cli make --btc-addr tb1q4gj53tuew3e6u4a32kdtle2q72su8te39dpceq\ - --xmr-addr 54EYTy2HYFcAXwAbFQ3HmAis8JLNmxRdTC9DwQL7sGJd4CAUYimPxuQHYkMNg1EELNP85YqFwqraLd4ovz6UeeekFLoCKiu\ - --btc-amount "0.0000135 BTC"\ - --xmr-amount "0.001 XMR" -``` - -The command will create a public offer based on the chosen parameters, spin up a listening `peerd` (in that case `0.0.0.0:9735`), and return the encoded offer (starting with `Offer:...`). - -This public offer should be shared by maker with taker. It also contains information on how to connect to maker (in that case `127.0.0.1:9735`). Additionally, it adds the public offers to the set of public offers in `farcasterd` that will be later used to initiate the swap upon takers requests. - -To get a detailed explaination of make and more details on all possible arguments you can change run `swap1-cli make --help`. - -## Take an offer - -Taker accepts offer and connects to maker's daemon node with the following command (run `swap2-cli take --help` for more details): - -Example of taking the offer above produced by maker: - -``` -swap2-cli take --btc-addr tb1qt3r3t6yultt8ne88ffgvgyym0sstj4apwsz05j\ - --xmr-addr 54EYTy2HYFcAXwAbFQ3HmAis8JLNmxRdTC9DwQL7sGJd4CAUYimPxuQHYkMNg1EELNP85YqFwqraLd4ovz6UeeekFLoCKiu\ - --offer Offer:... -``` - -The `--btc-addr` argument is the Bitcoin destination address in case the bitcoins need to be refunded or if the swap completes (depending on the swap role), the `--xmr-addr` for Monero, and finally the offer with `--offer` or `-o`. - -Upon taking the public offer, its deserialized content is printed and the user is asked for validation with `y` or `n`. - -:mag_right: Flag of interest: `--without-validation` or `-w`, for externally validated automated setups (skip validation in cli). - ---- - -If you want to use your full nodes and infrastructure you can change the configuration to the following. - -Farcaster needs to connect to three services to do actions on-chain and track on-chain events. Needed services are: an `electrum server`, a `monero daemon`, and a `monero rpc wallet`. - -You can launch all the needed services locally by running the following commands: - -```sh -bitcoind -server -testnet -electrs --network testnet -monerod --stagenet -monero-wallet-rpc --stagenet --rpc-bind-port 38083\ - --disable-rpc-login\ - --trusted-daemon\ - --password "pw"\ - --wallet-dir ~/.fc_monero_wallets -``` - -Then start the node with: - -``` -farcasterd -c farcasterd.toml -``` - -with `farcasterd.toml` configuration file: - -```toml -[syncers.testnet] -electrum_server = "tcp://localhost:60001" -monero_daemon = "http://localhost:38081" -monero_rpc_wallet = "http://localhost:{38083|38084}" -``` From e907d2a728b3d743735f86c4704f0d92520c4770 Mon Sep 17 00:00:00 2001 From: h4sh3d Date: Wed, 10 Aug 2022 13:52:41 +0200 Subject: [PATCH 2/2] doc: add instruction to clone the doc --- README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.md b/README.md index cd66e1f59..55d357169 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,11 @@ Farcaster Node is build on atomic swap primitives described in the [RFCs](https: ## Documentation Checkout Farcaster documentation in the [wiki](https://github.com/farcaster-project/farcaster-node/wiki). +If you want a local copy of the doc you can clone the wiki: + +``` +git clone https://github.com/farcaster-project/farcaster-node.wiki.git +``` ## Releases and Changelog