Skip to content

Commit

Permalink
Update Docs - Minor Fixes (#327)
Browse files Browse the repository at this point in the history
* Update 02-robots.md

Add `{% include improve %}` at end of section

* Update 03-premium.md

Add `{% include improve %}` at end of section

* Update 04-bonds.md

Add `{% include improve %}` at end of section
Update section to include `{{site.robosats.VARIABLE}}`

* Update 05-trade-escrow.md

Add `{% include improve %}` at end of section
Update section to include `{{site.robosats.VARIABLE}}`

* Update 07-wallets.md

Update section to include `{{site.robosats.VARIABLE}}`

* Update 09-swaps.md

Add `{% include improve %}` at end of section
Update section to include `{{site.robosats.VARIABLE}}`

* Update 12-prices.md

Add `{% include improve %}` at end of section

* Update 14-on-chain-payouts.md

Add `{% include improve %}` at end of section
  • Loading branch information
okada-blue authored Nov 24, 2022
1 parent acaf0db commit b1cc3ce
Show file tree
Hide file tree
Showing 8 changed files with 21 additions and 8 deletions.
2 changes: 2 additions & 0 deletions docs/_pages/docs/03-understand/02-robots.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,3 +53,5 @@ Under the hood, token creation in the RoboSats homepage is the process of genera
Your identity may be concealed by a robot identity, yet that is no excuse for being a difficult peer during trades. Other robots have robo-feelings too! Be succinct and respectful when chatting with peers; this will make for an easier and smoother experience on RoboSats. Never share more information than is absolutely necessary to complete the order.

All communications in RoboSats are PGP encrypted. The encrypted peer-to-peer chat messages are signed by each robot peer which proves no one intercepted the chat and is useful for resolving disputes. Refer to [Best Practices > PGP Encryption](https://learn.robosats.com/docs/pgp-encryption/) for additional information.

{% include improve %}
2 changes: 2 additions & 0 deletions docs/_pages/docs/03-understand/03-premium.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,3 +55,5 @@ Privacy is valuable for both buyer and seller and always worth a premium, whethe
The relative premium references the current exchange rates of public APIs, specifically blockchain.io and yadio.io prices. The median price of bitcoin in the selected currency is then calculated and displayed as the market rate your premium follows.

The 24-hour premium shown on the exchange interface is determined by the weighted median, not the mean, of successful orders in the past 24 hours. This calculation method is more resistant to outliers and more representative of peer-to-peer market consensus. In other words, the end-user should view this value as the premium they can roughly expect to pay for an order.

{% include improve %}
8 changes: 5 additions & 3 deletions docs/_pages/docs/03-understand/04-bonds.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ The fidelity bond is a small deposit that the user "locks" which will become unl

The RoboSats trade pipeline utilizes fidelity bonds to incentivize both the order maker and taker to play by the rules and not cheat their fellow robot. More specifically, the bonds are [hold invoices](https://github.com/lightningnetwork/lnd/pull/2022) using the Lightning Network; it's the tech that makes RoboSats possible!

By default, the bond is 3% of the total trade amount. Alternatively, order makers can customize this amount to be anywhere from 2% to 15%. Larger bonds mean more "skin in the game" that is required to trade.
By default, the bond is {{site.robosats.default_bond_size}}% of the total trade amount. Alternatively, order makers can customize this amount to be anywhere from {{site.robosats.min_bond_size}}% to {{site.robosats.max_bond_size}}%. Larger bonds mean more "skin in the game" that is required to trade.

The bond does not leave your Lightning wallet, but please know some wallets play nicer with RoboSats than others due to the nature of the Lightning hold invoice mechanic. Refer to [Understand > Wallets](https://learn.robosats.com/docs/wallets/) for additional information.

Expand All @@ -25,7 +25,7 @@ The bond does not leave your Lightning wallet, but please know some wallets play
First, refer to [Understand > Wallets](https://learn.robosats.com/docs/wallets/) for compatible Lightning wallets that will help make using RoboSats a smoother experience. Depending on the wallet, the invoice might show as a payment that is in transit, frozen, or even appearing to fail. Check the wallet compatability list!

Read the relevant guide depending on if you are making or taking the order:
* **Maker**: Select "Make Order" and modify the order conditions to your liking. The order can be customized to require a fidelity bond other than the default 3% of the total trade amount, ranging anywhere from 2% to 15%. Once complete, confirm with "Create Order" and then use the following QR code found in the "Contract Box" with your Lightning wallet to lock the indicated amount of sats for your fidelity bond. You can always cancel the untaken order while it is live and the bond will automatically unlock; however, if you try to cancel the order after it gets taken, you will forfeit your bond. *Note: Be prepared with your wallet beforehand because the order box expires in ten minutes.*
* **Maker**: Select "Make Order" and modify the order conditions to your liking. The order can be customized to require a fidelity bond other than the default {{site.robosats.default_bond_size}}% of the total trade amount, ranging anywhere from {{site.robosats.min_bond_size}}% to {{site.robosats.max_bond_size}}%. Once complete, confirm with "Create Order" and then use the following QR code found in the "Contract Box" with your Lightning wallet to lock the indicated amount of sats for your fidelity bond. You can always cancel the untaken order while it is live and the bond will automatically unlock; however, if you try to cancel the order after it gets taken, you will forfeit your bond. *Note: Be prepared with your wallet beforehand because the order box expires in ten minutes.*
* **Taker**: Browse the order book and find an order to your liking. Simply select the "Take Order" option and then use the following QR code found in the "Contract Box" with your Lightning wallet to lock the indicated amount of sats for your fidelity bond. *Note: Be prepared with your wallet beforehand because the order box expires in four minutes. If you do not proceed, the taken order is made public again.*

After the trade is completed and both robots are satisfied, the maker and taker bonds are unlocked. Technically, the locked bond never left your wallet; but take caution, if you fail to follow the contract obligations by trying to cheat or cancelling unilaterally, you will forfeit your fidelity bond.
Expand Down Expand Up @@ -59,10 +59,12 @@ As a sidenote, if RoboSats suddenly vanished or was shutdown, then bonds are aut

## **Don't Have Any Bitcoin for Bonds?**

Because the bonds require a Lightning hold invoice, what are you to do if you have no bitcoin to begin with? Even though the bond is typically just 3% of your total trade amount, this presents a real barrier to using RoboSats for the first time if your sat stack is non-existent.
Because the bonds require a Lightning hold invoice, what are you to do if you have no bitcoin to begin with? Even though the bond is typically just {{site.robosats.default_bond_size}}% of your total trade amount, this presents a real barrier to using RoboSats for the first time if your sat stack is non-existent.

Currently, bondless takers are not available; however, please know this is in the works! Bondless takers present a greater risk to the order maker since the taker has no skin in the game. It can be reasonable to expect higher premiums on orders that allow bondless takers.

There are a myriad of available apps and services where very small amounts of bitcoin can be earned. RoboSats does not endorse a specific app, but users have reported success with apps like [Stacker News](https://stacker.news/), [Fountain](https://www.fountain.fm/), [Carrot](https://www.earncarrot.com/), [THNDR](https://www.thndr.games/), etc.

Since the bond is a temporary hold on your funds, you could even borrow satoshis from a friend just for the fidelity bond. After the bond is unlocked from a successful trade, simply return the funds to your friend!

{% include improve %}
8 changes: 5 additions & 3 deletions docs/_pages/docs/03-understand/05-trade-escrow.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ src: "_pages/docs/03-understand/05-trade-escrow.md"

When selling bitcoin, a trade escrow is used to protect the buyer from fraud or nonpayment. The escrow acts as an assurance of security, leveraging Lightning [hold invoices](https://github.com/lightningnetwork/lnd/pull/2022) for a trustless transaction between robots.

The alotted time to submit (lock) a trade escrow is determined by the order maker. The escrow's expiry timer defaults to three hours; however, this can be customized to range anywhere from one to eight hours.
The alotted time to submit (lock) a trade escrow is determined by the order maker. The escrow's expiry timer defaults to {{site.robosats.hours_submit_escrow}} hours; however, this can be customized to range anywhere from 1 to 8 hours.

If the seller fails to lock the trade escrow within the order's given time limit, then the seller forfeits their fidelity bond. Refer to [Understand > Bonds](https://learn.robosats.com/docs/bonds/) for additional information on fidelity bonds. In addition, if a dispute is opened, then the satoshis in escrow are released to the dispute winner.

Expand All @@ -25,12 +25,12 @@ Be sure to use a Lightning wallet that plays well with RoboSats, refer to [Under
First, refer to [Understand > Wallets](https://learn.robosats.com/docs/wallets/) for compatible Lightning wallets that will help make using RoboSats a smoother experience. Depending on the wallet, the locked funds might show as a payment that is in transit, frozen, or even appearing to fail. Check the wallet compatability list!

Read the relevant guide depending on if you are making or taking an order to sell bitcoin:
* **Maker**: Select "Make Order" and modify the order conditions to your liking. The order can be customized to require an "Escrow Deposit Time-Out" (expiry timer) other than the default of three hours, ranging anywhere from one to eight hours. When your live order gets taken and the taker has submitted their fidelity bond, use the shown QR code found in the "Contract Box" with your Lightning wallet to lock the indicated amount of sats as collateral (escrow). *Note: Escrow funds are released to the buyer once you select "Confirm Fiat Received" which settles the order. Only confirm after the fiat has arrived in your account.*
* **Maker**: Select "Make Order" and modify the order conditions to your liking. The order can be customized to require an "Escrow Deposit Time-Out" (expiry timer) other than the default of {{site.robosats.hours_submit_escrow}} hours, ranging anywhere from 1 to 8 hours. When your live order gets taken and the taker has submitted their fidelity bond, use the shown QR code found in the "Contract Box" with your Lightning wallet to lock the indicated amount of sats as collateral (escrow). *Note: Escrow funds are released to the buyer once you select "Confirm Fiat Received" which settles the order. Only confirm after the fiat has arrived in your account.*
* **Taker**: Browse the order book and find an order to your liking. Simply select the "Take Order" option and lock your fidelity bond. Immediately after submitting the bond, use the following QR code found in the "Contract Box" with your Lightning wallet to lock the indicated amount of sats as collateral (escrow). *Note: Escrow funds are released to the buyer once you select "Confirm Fiat Received" which settles the order. Only confirm after the fiat has arrived in your account.*

As soon as the order taker locks their bond, the buyer and seller are required to submit the payout invoice and trade escrow, respectively, within the given time limit.

By default, the expiry timer is three hours; however, as the order maker, you can customize the timer to be anywhere from one hour to eight hours. In other words, modify the time allowed to lock the escrow funds and provide the payout invoice. Maybe you want an expedited transaction and will set the timer to a maximum of one hour instead of three hours.
By default, the expiry timer is {{site.robosats.hours_submit_escrow}} hours; however, as the order maker, you can customize the timer to be anywhere from 1 hour to 8 hours. In other words, modify the time allowed to lock the escrow funds and provide the payout invoice. Maybe you want an expedited transaction and will set the timer to a maximum of 1 hour instead of {{site.robosats.hours_submit_escrow}} hours.

If you lock the escrow funds before the buyer has provided the payout invoice, then you will have to wait to chat with your peer until after they have provided the invoice.

Expand Down Expand Up @@ -63,3 +63,5 @@ Although a very small window of time (about one second), the trade escrow could
Some Lightning wallets have difficulty with recognizing the Lightning hold invoice as a hold on your funds. As the seller, it is necessary to use a wallet that allows for multiple pending HTLCs since you will need to lock funds for a bond and then an escrow.

If issues arise, please reach out to the RoboSats Telegram group; but beware of scammers that may directly contact you and impersonate RoboSats staff! RoboSats staff will never directly contact you first. See [Contribute > Code > Communication Channels](https://learn.robosats.com/contribute/code/#communication-channels) for available Telegram groups.

{% include improve %}
2 changes: 1 addition & 1 deletion docs/_pages/docs/03-understand/07-wallets.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ Works as expected. The `lightning-cli pay <invoice>` command does not conclude w
It is an interface to LND, CLN and Eclair. It works as expected. It is extremely misleading with a full red screen "TIME OUT" a few seconds after sending the HTLC. Yet, if the user checks on the website, the invoice is correctly locked.

### Muun (Mobile)
Muun plays same nicely with hold invoices as Blixt or LND. You can be a seller in RoboSats using Muun and the user experience will be great. However, in order to be a buyer, you need to submit an onchain address for the payout, a lightning invoice won't work. Muun is _fee siphoning attacking_ any sender to Muun wallet. There is a mandatory hop trough a private channel with a fee of +1500ppm. RoboSats will strictly not route a buyer payout for a net loss. Given that RoboSats trading fees are 0.2% and it needs to cover the routing fees, **RoboSats will never find a suitable route to a Muun wallet user**. At the moment, RoboSats will scan your invoice for routing hints that can potentially encode a _fee siphoning attack_.If this trick is found, the invoice will be rejected: submit an onchain address instead for an on-the-fly swap.
Muun plays same nicely with hold invoices as Blixt or LND. You can be a seller in RoboSats using Muun and the user experience will be great. However, in order to be a buyer, you need to submit an onchain address for the payout, a lightning invoice won't work. Muun is _fee siphoning attacking_ any sender to Muun wallet. There is a mandatory hop trough a private channel with a fee of +1500ppm. RoboSats will strictly not route a buyer payout for a net loss. Given that RoboSats trading fees are {{site.robosats.total_fee}}% and it needs to cover the routing fees, **RoboSats will never find a suitable route to a Muun wallet user**. At the moment, RoboSats will scan your invoice for routing hints that can potentially encode a _fee siphoning attack_.If this trick is found, the invoice will be rejected: submit an onchain address instead for an on-the-fly swap.

### Phoenix (Mobile)
Phoenix works very well as an order taker. Phoenix will also work well as an order maker as long as the order settings `public duration` + `deposit duration` are lower than 10 hours. Otherwise you might have problems locking the maker bond. If the total duraton of bonds/escrow invoices exceeds 450 blocks, Phoenix will not allow users to lock the bond (`Cannot add htlc (...) reason=expiry too big`).
Expand Down
4 changes: 3 additions & 1 deletion docs/_pages/docs/03-understand/09-swaps.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ recommendations:

1. If you are the **seller** - you will be **receiving** on-chain BTC; setting
the premium slightly below 0% (eg. -0.1%, -0.5%) will make your offer
attractive. The taker already pays 0.125% fees on the trade plus they have
attractive. The taker already pays {{site.robosats.taker_fee}}% fees on the trade plus they have
to pay mining fees for sending the on-chain BTC.

2. If you are the **buyer** - you will be **sending** on-chain BTC; setting the
Expand All @@ -79,3 +79,5 @@ recommendations:
These are just general recommendations about what premium to set to get started
with swaps, but at the end of the day, the price is what the market sets, so
experiment and see what works for you.

{% include improve %}
2 changes: 2 additions & 0 deletions docs/_pages/docs/03-understand/12-prices.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,3 +92,5 @@ First, check the current [currencies.json](https://github.com/Reckless-Satoshi/r
If you find a currency that is missing from RoboSats and also available in any of the two referenced APIs, then you can directly edit the currencies.json and [FlagsWithProps.tsx](https://github.com/Reckless-Satoshi/robosats/blob/main/frontend/src/components/FlagWithProps/FlagWithProps.tsx) files.

After merging the pull request, the added currency will now be available in RoboSats!

{% include improve %}
1 change: 1 addition & 0 deletions docs/_pages/docs/03-understand/14-on-chain-payouts.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,3 +59,4 @@ The exchange summary dialog displays the current value of the on-chain payout fe
<img src="/assets/images/understand/14-on-chain-payouts/exchange-summary.png"/>
</div>

{% include improve %}

0 comments on commit b1cc3ce

Please sign in to comment.