feat x/bridge: added module docs (#7854)

* feat x/bridge: added module docs

* typo fix

* docs linter fix

x/bridge/images/inbound_transfer.puml

@@ -53,22 +53,22 @@ Block <-- val3_2 : process
 Block <-- val4_2 : process
 Block <-- val5_2 : process
 
-action "Process each\nMsgInboundTransfer" as val1_act_1
-action "Process each\nMsgInboundTransfer" as val2_act_1
-action "Process each\nMsgInboundTransfer" as val3_act_1
-action "Process each\nMsgInboundTransfer" as val4_act_1
-action "Process each\nMsgInboundTransfer" as val5_act_1
+node "x/bridge" as val1_act_1
+node "x/bridge" as val2_act_1
+node "x/bridge" as val3_act_1
+node "x/bridge" as val4_act_1
+node "x/bridge" as val5_act_1
 
 val1_2 --> val1_act_1
 val2_2 --> val2_act_1
-val3_2 --> val3_act_1
+val3_2 --> val3_act_1 : Process each\nMsgInboundTransfer
 val4_2 --> val4_act_1
 val5_2 --> val5_act_1
 
 action "Accumulate votes x3" as val1_act_2
-action "Is not a part\nof the signers set" as val2_act_2 #red
+action "Accumulate votes x3" as val2_act_2
 action "Accumulate votes x3" as val3_act_2
-action "Is not a part\nof the signers set" as val4_act_2 #red
+action "Accumulate votes x3" as val4_act_2
 action "Accumulate votes x3" as val5_act_2
 
 val1_act_1 --> val1_act_2
@@ -77,22 +77,40 @@ val3_act_1 --> val3_act_2
 val4_act_1 --> val4_act_2
 val5_act_1 --> val5_act_2
 
-action "Call tokenfactory mint" as val1_act_3
-action "Call tokenfactory mint" as val3_act_3
-action "Call tokenfactory mint" as val5_act_3
+action "**Mint** to the dest addr" as val1_act_3
+action "**Mint** to the dest addr" as val2_act_3
+action "**Mint** to the dest addr" as val3_act_3
+action "**Mint** to the dest addr" as val4_act_3
+action "**Mint** to the dest addr" as val5_act_3
 
 val1_act_2 --> val1_act_3
+val2_act_2 --> val2_act_3
 val3_act_2 --> val3_act_3
+val4_act_2 --> val4_act_3
 val5_act_2 --> val5_act_3
 
-node "Submit the block" as consensus
+action "Finalize the transfer" as val1_act_4
+action "Finalize the transfer" as val2_act_4
+action "Finalize the transfer" as val3_act_4
+action "Finalize the transfer" as val4_act_4
+action "Finalize the transfer" as val5_act_4
 
-val1_act_3 --> consensus
-val3_act_3 --> consensus
-val5_act_3 --> consensus
+val1_act_3 --> val1_act_4
+val2_act_3 --> val2_act_4
+val3_act_3 --> val3_act_4
+val4_act_3 --> val4_act_4
+val5_act_3 --> val5_act_4
 
-note left of consensus
-    The transfer is done!
-end note
+action "Consensus!" as consensus
+
+val1_act_4 --> consensus
+val2_act_4 --> consensus
+val3_act_4 --> consensus
+val4_act_4 --> consensus
+val5_act_4 --> consensus
+
+actor "Happy client" as client1 #lightgreen;line:green;line.bold;text:green
+
+consensus --> client1  :coins are minted to the destination addr
 
 @enduml

x/bridge/images/mint_burn.puml

@@ -0,0 +1,43 @@
+@startuml
+
+participant "Alice BTC addr" as alice_btc
+participant "BTC vault" as btc_vault
+participant "Valset" as valset
+participant "x/bridge" as bridge
+participant "x/tokenfactory" as tokenfactory
+participant "Alice OSMO addr" as alice_osmo
+
+== BTC to OSMO ==
+
+alice_btc --> btc_vault : Send tx with the osmo\naddress in memo
+valset --> btc_vault : Observe the tx
+valset --> bridge : **MsgInboundTransfer**
+bridge --> tokenfactory : Mint tokens to\nthe osmo address
+note over tokenfactory
+  x/bridge is the admin
+end note
+tokenfactory --> alice_osmo : Update Alice balance
+
+alt failure
+  bridge --> alice_btc : Refund
+end
+
+== OSMO to BTC ==
+
+alice_osmo --> bridge : **MsgOutboundTransfer**
+bridge --> tokenfactory : Burn tokens from\nthe osmo address
+note over tokenfactory
+  x/bridge is the admin
+end note
+tokenfactory --> alice_osmo : Update Alice balance
+
+valset --> bridge : Observe x/bridge event
+
+valset --> btc_vault : Release BTC for Alice
+valset --> alice_btc : Send BTC
+
+alt failure
+  bridge --> alice_osmo : Refund
+end
+
+@enduml

x/bridge/images/observer.puml

@@ -0,0 +1,47 @@
+@startuml
+
+left to right direction
+
+legend right
+|= Color  |= Transfer |
+|<#green> | Outbound  |
+|<#blue>  | Inbound   |
+endlegend
+
+node "Bitcoin" as bitcoin
+node "Osmosis" as osmosis
+node "Ethereum" as eth
+
+folder "Observer" as observer {
+  folder "Bitcoin" as bitcoin_observer {
+    component "Client" as bitcoin_chain_client
+    component "Observer" as bitcoin_observer_1
+  }
+
+  folder "Ethereum" as eth_observer {
+      component "Client" as eth_chain_client
+      component "Observer" as eth_observer_1
+    }
+
+  folder "Osmosis" as osmosis_observer {
+    component "Client" as osmosis_chain_client
+    component "Observer" as osmosis_observer_1
+  }
+}
+
+bitcoin -d-> bitcoin_observer_1 #blue : inbound transfer
+bitcoin_observer_1 --d-> osmosis_chain_client #blue
+
+osmosis_observer_1 --u-> bitcoin_chain_client #green
+bitcoin_chain_client -u-> bitcoin #green : release coins
+
+eth -d-> eth_observer_1 #blue : inbound transfer
+eth_observer_1 --d-> osmosis_chain_client #blue
+
+osmosis_observer_1 --u-> eth_chain_client #green
+eth_chain_client -u-> eth #green : release coins
+
+osmosis_chain_client -d-> osmosis #blue : **MsgInboundTransfer**
+osmosis -u-> osmosis_observer_1 #green : **EventOutboundTransfer**
+
+@enduml

x/bridge/images/outbound_transfer.puml

@@ -0,0 +1,113 @@
+@startuml
+
+skinparam package<<Hidden>> {
+  borderColor Transparent
+  backgroundColor Transparent
+  fontColor Transparent
+  stereotypeFontColor Transparent
+}
+
+actor "Client" as client
+
+folder "Valset" as valset1 {
+    cloud "Validator 1" as val1 #lightgreen
+    cloud "Validator 2" as val2
+    cloud "Validator 3" as val3 #lightgreen
+    cloud "Validator 4" as val4
+    cloud "Validator 5" as val5 #lightgreen
+}
+
+val1 -> val2 #white
+val2 -> val3 #white
+val3 -> val4 #white
+val4 -> val5 #white
+
+note bottom of valset1
+    Green validators are
+    running x/bridge observers.
+
+    Let's say that we need **three**
+    votes to process the transfer.
+end note
+
+client --> val2 : **MsgOutboundTransfer** to the selected node
+client --> val4 #white
+
+node "x/bridge" as bridge
+
+val2 --> bridge : **InboundTransfer**
+val4 --> bridge #white
+
+node "x/tokenfactory" as tokenfactory
+
+bridge <-left-> tokenfactory : **Burn** from\nthe source addr
+
+artifact "**EventOutboundTransfer**" as event
+
+bridge --> event : Produce the event
+
+folder "Valset" as valset2 {
+    cloud "Validator 1" as val1_2 #lightgreen
+    cloud "Validator 2" as val2_2
+    cloud "Validator 3" as val3_2 #lightgreen
+    cloud "Validator 4" as val4_2
+    cloud "Validator 5" as val5_2 #lightgreen
+}
+
+val1_2 -> val2_2 #white
+val2_2 -> val3_2 #white
+val3_2 -> val4_2 #white
+val4_2 -> val5_2 #white
+
+val1_2 -u-> event: observe
+val3_2 -u-> event: observe
+val5_2 -u-> event: observe
+
+
+component "     TSS Server    " as tss
+
+val1_2 -d-> tss : sign
+val3_2 -d-> tss : sign
+val5_2 -d-> tss : sign
+
+action "Collect signatures x3" as signatures
+
+tss --> signatures
+
+action "Leader election" as leader
+
+note left of leader
+    Leader is the one who
+    broadcasts the transfer
+    to the external chain
+end note
+
+signatures --> leader
+
+folder "Valset" as valset3 {
+    cloud "Validator 1" as val1_3 #lightgreen
+    cloud "Validator 2" as val2_3
+    cloud "Validator 3" as val3_3 #lightgreen
+    cloud "Validator 4" as val4_3
+    cloud "Validator 5" as val5_3 #lightgreen
+
+    val1_3 -> val2_3 #white
+    val2_3 -> val3_3 #white
+    val3_3 -> val4_3 #white
+    val4_3 -> val5_3 #white
+}
+
+leader -d-> val1_3 #white
+leader -d-> val3_3 #white
+leader -d-> val5_3 : choose leader
+
+node "BTC vault" as vault
+
+val1_3 --> vault #white
+val5_3 --> vault : release coins
+
+actor "Happy client" as client1 #lightgreen;line:green;line.bold;text:green
+
+vault --> client1 : coins are transferred to the destination addr
+
+@enduml