Emphasize that ygen uses only single UTXO as fbond

At least two people have been burned by creating two transactions
sending bitcoins to two timelocked addresses, and then finding that
yield-generator announces only one of them.

This commit expands the section talking about how only one UTXO will
be used. It also edits the text to refer to yield-generator's fidelity
bonds only in the singular, as previously they were referred to in
the plural (i.e. "fidelity bonds"), which possibly added to user's
confusion.

docs/fidelity-bonds.md

@@ -54,16 +54,17 @@ passing the relevant CLI option when running a script (for example
 list of options.
 
 
-## How to use fidelity bonds as a yield-generator
+## How to create and use a fidelity bond as a yield-generator
 
-You need to create a fidelity bond wallet and run the yield-generator script on it. The yield
-generator will automatically announce the most valuable fidelity bond in its wallet. Fidelity bonds
-are only supported for native segwit wallets.
+You need to create a fidelity bond wallet and run the yield-generator script on it. In practice the
+vast majority of wallets will contain just a single fidelity bond. If the wallet for some reason
+has multiple fidelity bonds then the yield generator will automatically announce the most valuable
+fidelity bond in its wallet. Fidelity bonds are only supported for native segwit wallets.
 
-### Creating a JoinMarket wallet which supports fidelity bonds
+### Creating a JoinMarket wallet which supports creating a fidelity bond
 
 When generating a JoinMarket wallet on the command line, supporting versions
-will offer an option to make the wallet support fidelity bonds.
+will offer an option to make the wallet support creating a fidelity bond.
 
     (jmvenv) $ python3 wallet-tool.py generate
     Would you like to use a two-factor mnemonic recovery phrase? write 'n' if you don't know what this is (y/n): n
@@ -83,7 +84,7 @@ as a backup. It is also recommended to write down the name of the creating walle
 "JoinMarket" and that the fidelity bond option was enabled. Writing the wallet
 creation date is also useful as it can help with rescanning.
 
-#### Adding fidelity bonds to an existing wallet
+#### Adding fidelity bond support to an existing wallet
 
 On any **native segwit** wallet this can be done by using the `recover` method:
 
@@ -93,7 +94,7 @@ And then choosing `yes` to create a fidelity bond wallet.
 
 #### Note on privacy
 
-Bitcoin transactions which create fidelity bonds will be published to the entire world, so before
+A Bitcoin transaction which creates a fidelity bond will be published to the entire world, so before
 creating them make sure the coins are not linked to any of your privacy-relevant information.
 Perhaps mix with JoinMarket. Also, use a sweep transaction which does not create a change output
 when funding the timelocked address. Change addresses can also leak privacy information and the
@@ -107,12 +108,12 @@ privacy-relevant information linked to you has been leaked.
 This can all be done with `sendpayment.py` and coin control (i.e. freezing the UTXOs that you dont
 want to spend).
 
-### Obtaining time-locked addresses
+### Obtaining a time-locked address
 
 The `wallet-tool.py` script supports a new method `gettimelockaddress` used for
-obtaining time-locked addresses. If coins are sent to these addresses they will
-be locked up until the timelock date passes. Only mixdepth zero can have
-fidelity bonds in it.
+obtaining time-locked addresses. If bitcoins are sent to these addresses they will
+be locked up until the timelock date passes. Only mixdepth zero can have a
+fidelity bond in it.
 
 This example creates an address which locks any coins sent to it until January 2025.
 
@@ -161,10 +162,10 @@ Once unfrozen and untimelocked the coins can be spent with a non-coinjoin transa
 of timelocked addresses to any other wallets, as they use custom scripts. You must spend them from
 JoinMarket itself.
 
-### How many coins to lock up and for how long?
+### What amount of bitcoins to lock up and for how long?
 
-Fidelity bonds UTXOs are valuable as soon as they confirmed. The simplified formula for a fidelity
-bond value with locked coins is:
+A fidelity bond is valuable as soon as the transaction creating it becomes confirmed. The
+simplified formula for a fidelity bond's value is:
 
     bond_value = (locked_coins * (exp(interest_rate * locktime) - 1))^2
 
@@ -197,14 +198,28 @@ At any time you can use the orderbook watcher script to see your own fidelity bo
 
 Consider also the [warning on the bitcoin wiki page on timelocks](https://en.bitcoin.it/wiki/Timelock#Far-future_locks).
 
-I would recommend locking as many coins as you are comfortable with for a period of between 6
+I would recommend locking as many bitcoins as you are comfortable with for a period of between 6
 months and 2 years. Perhaps at the very start lock for only 1 month or 2 months(?) It's a
 marketplace and the rules are known to all, so ultimately you'll have to make your own decision.
 
-### Can I add coins to a fidelity bond that already exists?
+### Can my yield-generator use multiple timelocked addresses or UTXO?
 
-No. Sending more coins to the same timelocked address will not add to the existing fidelity bond,
-but instead create a new one with the same locktime.
+Alternatively: Can I add more bitcoins to a fidelity bond that already exists?
+
+No. Creating a new transaction which sends more bitcoins to a timelocked address will not add to
+the existing fidelity bond, but instead create a new one. The two fidelity bonds will not be
+combined. A yield-generator only announces a single fidelity bond transaction UTXO, and it choses
+the most valuable one.
+
+As a yield-generator, you are generally stuck with the fidelity bond you create until it expires.
+You can still create a new fidelity bond and use that instead, but the old one will be unused. If you want
+to increase the value of a fidelity bond the best way to do that is to wait until it expires and
+then spend from the timelocked address combining with extra UTXOs you want to add, into a new
+timelocked address. You can use JoinMarket's coin control feature to control this.
+
+This is one reason why a yield-generator who creates a fidelity bond for the first time should only
+lock up coins for a relatively short time, so that they can try out the whole thing, and don't
+have to wait too long before they add more coins.
 
 ### Creating watch-only fidelity bond wallets