Skip to content

Usage

Jump to bottom
h4sh3d edited this page Aug 15, 2022 · 18 revisions

🚨 The following section focus on how to use the Farcaster Node to propose and run atomic swaps. Keep in mind that this software remains new and should be used at your own risks.

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 encapsulates informations about a trade of Bitcoin and Monero. One will make 🔨 an offer, e.g. a market maker, and one will try to take 💰 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.

🔨 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.

🔎 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.

🔎 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.

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 moneroj 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 swapids of the running swaps, use swap-cli ls.

💰 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.

Clone this wiki locally