Update spec with token recovery (#59)

# Description
- Update diagram with automatic token recovery (send back to user) and
return ticket.

spec/spec.md

@@ -1,4 +1,4 @@
-# Coreumbrdige XRPL spec.
+# Coreumbridge XRPL spec.
 
 The spec describes the technical solution of the XRPL two-way bridge.
 
@@ -8,10 +8,10 @@ The spec describes the technical solution of the XRPL two-way bridge.
 
 ### XRPL multi-signing account
 
-The account holds the tokens issued on the XRPL on its balance. Depending on workflow it either uses the received tokens
+The account holds the tokens issued on the XRPL on its balance. Depending on the workflow it either uses the received tokens
 balance to send to XRPL accounts (in case the account is not an issuer) or mints and sends the tokens to XRPL accounts (
-in case it is the coreum token representation issued by the address). The account uses the multi-signing and public keys
-associated with each relayer from the contract for the transactions signing.
+in case it is the Coreum token representation issued by the address). The account uses the multi-signing and public keys
+associated with each relayer from the contract for the transaction signing.
 
 ### Bridge contract
 
@@ -21,18 +21,18 @@ settings of the bridge and execute the workflows' recovery.
 
 #### Tokens registry
 
-Before the bridging, a token (XRPL or coreum) should be manually registered for the bridging. The tokes that are not
+Before the bridging, a token (XRPL or Coreum) should be manually registered for the bridging. The tokens that are not
 registered can't be bridged.
 
 ##### XRPL originated tokens registration
 
-All tokens issued on XRPL that can be bridged from the XRPL to the coreum and back must have a representation on the
-coreum. Such tokens should be registered by owner on the contract side with the `XRPL issuer`, `XRPL currency`, `fees`,
-`token decimals` (always 15), `sending precision` and `max holding amount`. The `sending precision` and
-` max holding amount`` should be provided taking into account the [Amount rounding handling](#amount-rounding-handling).
-The token's  `denom`is built uniquely by the contract using the`XRPL issuer`, `XRPL currency`, `block time`hash and`xrpl`prefix.
-Required features for the issuance are`minting`, `burning`, and `IBC`. During the registration, the contract issues a
-token and will be responsible for its minting later. After the registration, the contract triggers
+All tokens issued on XRPL that can be bridged from the XRPL to the Coreum and back must have a representation on the
+Coreum. Such tokens should be registered by owner on the contract side with the `XRPL issuer`, `XRPL currency`, `fees`,
+`sending precision` and `max holding amount`. The `token decimals` (always 15) will be set by the contract. The `sending precision` and
+`max holding amount` should be provided taking into account the [Amount rounding handling](#amount-rounding-handling).
+The token's `denom` is unique and is built by the contract using the `XRPL issuer`, `XRPL currency`, `block time` hash and `xrpl` prefix.
+Required features for the issuance are `minting`, `burning`, and `IBC`. During the registration, the contract issues a
+token and will be responsible for its minting when a token is bridged from the XRPL to Coreum. After the registration, the contract triggers
 the `submit-trust-set-for-xrpl-token` operation to allow the multi-signing account to receive that token. The value of
 the trustset limit amount will be provided during constract instantiation and saved in the config of the contract.
 Check [register-token workflow](#register-token) for more details.
@@ -52,17 +52,18 @@ that fee-balance might also minimise that risk.
 
 ##### Coreum originated tokens registration
 
-All tokens issued on the coreum that can be bridged from the coreum to XRPL and back must have a representation on the
+All tokens issued on the Coreum that can be bridged from the Coreum to XRPL and back must have a representation on the
 XRPL, managed by the multi-signing account. Such tokens should be registered by owner on the contract side with the
 `coreum denom`, `token decimals`, `sending precision`, `max holding amount` and `fees`. The `sending precision` and
 `max holding amount` should be provided taking into account the [Amount rounding handling](#amount-rounding-handling).
-The `XRPL currency` will be uniquely generated by the contract using the `denom` and will be used as a representation of
+The `XRPL currency` will be uniquely generated by the contract using the `denom`, `decimals`, `block time` hash with a `coreum` prefix and
+encoding it into the hexadecimal currency notation used in XRPL. This will be used as a representation of
 that token on the XRPL side.
 Check [workflow](#register-token) for more details.
 
 ##### Max holding amount and sending precision update
 
-It is possible to update both `max holding amount` and `sending precision` for both XRPL and coreum originated tokens. The
+It is possible to update both `max holding amount` and `sending precision` for both XRPL and Coreum originated tokens. The
 owner can do it by calling the contract.
 The contract updates the `sending precision` in the token registry and removes all pending evidences with
 `sending from XRPL to coreum` type data from the evidence queue. We need it to avoid evidence inconsistency, since an
@@ -111,7 +112,7 @@ idempotent. And let some operations be safely re-processed at any time.
 The XRPL tickets allow us to execute a transaction with non-sequential sequence numbers, hence we can execute multiple
 transactions in parallel. Any workflow can allocate a ticket and the ticket allocation mechanism either returns a ticket
 number or errors out, in case of lack of the free tickets. The ticket re-allocation will be triggered by the tx
-conformation (Submit XRPL transaction last step) once the used tickets count is gather that allowed threshold. The
+comfirmation (Submit XRPL transaction last step) once the used tickets count is greater than the allowed threshold. The
 contract initiates the `submit-increase-tickets` operation to increase the amount. Once the operation is confirmed, the
 contract increases the free slots on the contract as well (based on the tx result).
 
@@ -121,7 +122,7 @@ Check [workflow](#allocate-ticket) for more details.
 
 ##### Sending of tokens from XRPL
 
-The contract receives the `send-to-coreum` request and starts the corresponding [workflow](#send-from-xrpl-to-coreum).
+The contract receives a `save-evidence` request with an `XRPL-to-coreum-transfer` evidence and starts the corresponding [workflow](#send-from-xrpl-to-coreum).
 
 ##### Sending of tokens to XRPL
 
@@ -138,12 +139,12 @@ The transfer fee is the fee for the tokens which charge the commission for the t
 the locked tokens back in case they are locked either on the contract or on the multi-signing address. Both fees will be
 taken from the amount a user sends.
 The bridging fees are distributed across the relayer addresses
-after the successful execution of the sending, and locked until a relayer manually requests it. After such a request the
+after the execution of the sending, and locked until a relayer manually requests it. After such a request the
 accumulated bridging fee will be distributed equally to the current relayer addresses.
 
 ###### Fee charging from XRPL to Coreum
 
-When a user transfers a token from the XRPL to coreum we can compute the expected received amount based on the formula:
+When a user transfers a token from the XRPL to Coreum we can compute the expected received amount based on the formula:
 
 ```text
 roundedRatAmount := roundWithSendingPrecision(sendingRatAmount)
@@ -161,7 +162,7 @@ If a token uses the transfer fee, we don't include it here because it will be in
 
 ###### Fee charging from Coreum to XRPL
 
-When a user transfers a token from the coreum to XRPL account we can compute the expected received amount based on
+When a user transfers a token from the Coreum to an XRPL account we can compute the expected received amount based on
 formula:
 
 ```text
@@ -175,7 +176,7 @@ roundedRatAmount := roundWithSendingPrecision(sendingRatValueWithoutAllFees)
 We don't include the transfer rate to the bridgingFee intentionally to simplify the calculation, but it will be included
 at the step of the `offline` `bridgingFee` calculation.
 
-The contract receives the `send to XRPL` request for a user, executes the formula and checks, if after the calculation
+The contract receives the `send-to-XRPL` request for a user, executes the formula and checks, if after the calculation
 the `roundedRatAmount <= 0` or `roundedRatAmount > max allowed value` returns an error. If all validation pass, the
 contract creates a sending operation with roundedRatAmount, and relayers fees. The rounding reminder remains on the
 contract balance.
@@ -189,7 +190,7 @@ token might be changed during the time, so the fee should be changed accordingly
 
 All accounts that can interact with the contract or multi-signing account are registered on the contract. And can be
 rotated using the key rotation workflow. The workflow is triggered by the owner. The owner provides
-the new relayer coreum addresses, XRPL public keys and signing/evidence threshold.
+the new relayer Coreum addresses, XRPL public keys and signing/evidence threshold.
 It is possible to start the keys rotation workflow in case the contract is disabled, but there is not keys rotation
 in-process. That option gives and owner an ability to rotate the keys in case the contract is disabled because of the
 malicious relayer, or the malicious relayer disabled it. Check [workflow](#rotate-keys) for more details.
@@ -221,7 +222,7 @@ type. As the result some discrepancy might happen, examples:
 
 ### Issues:
 
-1. Send low and high amount to coreum and return high and low back.
+1. Send low and high amount to Coreum and return high and low back.
    1.1. XRPLUser sends 10 XRPL originated token to coreumUser (bridge account balance: 10, coreumUser balance: 10)
    1.2. XRPLUser sends 1e17 XRPL originated token to coreumUser (bridge account balance: 1e17, coreumUser balance: 1e17 + 10)
    1.3. coreumUser sends 1e17 XRPL originated token to XRPLUser (bridge account balance: 0, XRPLUser balance: 1e17)
@@ -230,7 +231,7 @@ type. As the result some discrepancy might happen, examples:
 The same issue might be in case the bridge account holds 1e20 and receive 1 XRPL originated token. The delivered amount will
 contain the 1 XRPL originated token, but the bridge balance will remain the same.
 
-2. Send coreum originated token to XRPL, mint it there, and send back.
+2. Send Coreum originated token to XRPL, mint it there, and send back.
    1.1. CoreumUser sends 1e17 Coreum originated token to XRPLUser (bridge account balance: 0, bridge contract: 1e17,
    XRPLUser balance: 1e17)
    1.2. XRPLUser mints 100 tokens on the XRPL by sending 49, 49, 2 amounts to a recipient with low balance and back.
@@ -268,8 +269,8 @@ sendingPrecision = sendingPrecision - complexityCoefficient.
 The `1e16` is the minimum amount a holder should have to produce one token on the XRPL submitting one transaction.
 
 The `totalTokenSupply` here is the total issued amount on the chain. For the XRPL chain we take simply total supply,
-but for the coreum chain we take the total supply divided by the token decimals, since the coreum chain uses the integer
-for the amounts, but XRPL float.
+but for the Coreum chain we take the total supply divided by the token decimals, since the Coreum chain uses the integer
+for the amounts, but XRPL uses float.
 
 The `complexityCoefficient` is coefficient we use to improve the `risks handling`. Without that coefficient the formula
 provides a `risks handling` when an account holding the total supply is able to produce `significant amount`
@@ -332,7 +333,7 @@ min sending amount = 0.001
 ```
 
 ```text
-token total supply on coreum XRPL: 1e11 * 1e6(decimals)
+token total supply on Coreum: 1e11 * 1e6(decimals)
 complexityCoefficient: 4
 ratio = 1e11 * 1e6(decimals)/1e6(decimals) / 1e16 = 0.00001
 sendingPrecision = 4 - complexityCoefficient = 0