Sequence diagram for all the components (#1083)

doc/internal/.gitignore

@@ -1 +1 @@
-*.png
+*.svg

doc/internal/gen_svg.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+THIS_DIR=`pwd`
+PUML_FILES=`ls *.puml global_seq_diag/*.puml`
+rm -f *.svg
+for file in $PUML_FILES; do
+    echo $file
+    plantuml -tsvg $file -o "$THIS_DIR/build"
+done

doc/internal/global_seq_diag/erc20.puml

@@ -0,0 +1,48 @@
+@startuml
+autonumber
+
+skinparam roundcorner 20
+
+participant "Cape Contract" as C
+participant "Ethereum Query Service" as EQS
+participant "Alice's Wallet" as W_A
+participant "Bob's Wallet" as W_B
+participant "Relayer" as R
+participant "Freezer" as F
+participant "Auditor" as A
+participant "Ethereum Wallet Eve" as ETH_WX
+
+group Conversion between ERC20 and CAP assets
+
+    group Sponsor
+        W_A -> C: **sponsor_cape_asset**(USDC, asset_def)
+        C -> C: **update_list_registered_assets**(USDC, asset_def)
+    end group
+
+    group Wrap
+        W_B -> C: **depositErc20**(record_opening,USDC)
+        C -> EQS: new_erc_deposit_event(record_opening, USDC, bob_eth_address)
+        EQS -> W_A: new_erc_deposit_event(record_opening, USDC, bob_eth_address)
+        EQS -> W_B: new_erc_deposit_event(record_opening, USDC, bob_eth_address)
+        W_A -> R: transfer_tx:= **build_transfer_tx**(...)
+        R -> R: b:=**new_block**(transfer_tx,[])
+        R -> C: b
+        C -> EQS: new_block_event(b,[record_opening])
+        EQS -> W_A: new_block_event(b,[record_opening])
+        EQS -> W_B: new_block_event(b,[record_opening])
+        EQS -> A: new_block_event(b,[record_opening])
+        EQS -> F: new_block_event(b,[record_opening])
+        W_B -> W_B: **update_local_state_from_erc_20_deposit**(record_opening)
+
+    end group
+
+    group Unwrap
+        W_A -> R: burn_tx:= **build_burn_tx**(record_opening,eve_eth_address,...)
+        R -> R: b:= **new_block_from**(burn_tx,[])
+        R -> C: b
+        C -> ETH_WX: (USDC,10)
+    end group
+
+end group
+
+@enduml

doc/internal/global_seq_diag/freeze.puml

@@ -0,0 +1,37 @@
+@startuml
+autonumber
+
+skinparam roundcorner 20
+
+participant "Cape Contract" as C
+participant "Ethereum Query Service" as EQS
+participant "Alice's Wallet" as W_A
+participant "Bob's Wallet" as W_B
+participant "Relayer" as R
+participant "Freezer" as F
+participant "Auditor" as A
+
+group Freeze
+
+   note left F: We assume the Auditor shares Bob's asset record with the Freezer \n who freezes this record.
+
+   F -> F: freeze_tx:=**build_freeze_tx**(bob_asset_record)
+   F -> R: freeze_tx
+   R -> R: b:= **create_new_block**(freeze_tx,[])
+   R -> C: b
+   C -> EQS: new_block_event(b,[])
+   EQS -> W_A: new_block_event(b,[])
+   EQS -> W_B: new_block_event(b,[])
+   EQS -> F: new_block_event(b,[])
+   EQS -> A: new_block_event(b,[])
+   note left W_B: Bob tries to spend his frozen asset record
+   W_B -> W_B: transfer_tx_invalid := **build_transfer_tx**(...)
+   W_B -> R: transfer_tx_invalid
+   R -> R: b := **new_block**(transfer_tx_invalid,[...])
+   R -> C: b
+   note right C: The block is rejected because Bob's transaction is invalid
+   C -> C: <color:red>**Error**</color>
+
+end group
+
+@enduml

doc/internal/global_seq_diag/mint.puml

@@ -0,0 +1,33 @@
+@startuml
+autonumber
+
+skinparam roundcorner 20
+
+participant "Cape Contract" as C
+participant "Ethereum Query Service" as EQS
+participant "Alice's Wallet" as W_A
+participant "Bob's Wallet" as W_B
+participant "Relayer" as R
+participant "Freezer" as F
+participant "Auditor" as A
+
+
+group Mint
+    note left W_A: Alice mints some asset records, and she is the recipient
+    W_A -> W_A: (mint_tx,[alice_memo]) := **build_mint_tx**(alice_address,fee, alice_coin, 50000, alice_address)
+    W_A -> R: (mint_tx,[alice_memo])
+    R -> R: b:= **create_new_block**(mint_tx,[alice_memo])
+    R -> C: b
+    C -> EQS: **new_block_event**(b,[])
+    EQS -> W_A: **new_block_event**(b,[])
+    EQS -> W_B: **new_block_event**(b,[])
+    EQS -> A: **new_block_event**(b,[])
+    EQS -> F: **new_block_event**(b,[])
+    note left W_B: Bob receives no memo
+    W_B -> W_B: [] := **fetch_memos_from**([alice_memo])
+    note left W_A: Alice's wallet decrypts and stores the new asset record for further spending
+    W_A -> W_A: [alice_memo] := **fetch_memos_from**([alice_memo])
+    W_A -> W_A: **update_local_state_from**(alice_memo)
+end group
+
+@enduml

doc/internal/global_seq_diag/transfer.puml

@@ -0,0 +1,44 @@
+@startuml
+autonumber
+
+skinparam roundcorner 20
+
+participant "Cape Contract" as C
+participant "Ethereum Query Service" as EQS
+participant "Alice's Wallet" as W_A
+participant "Bob's Wallet" as W_B
+participant "Relayer" as R
+participant "Freezer" as F
+participant "Auditor" as A
+participant "AddressBook" as AB
+
+group Transfer
+
+    W_A -> AB: **get_enc_pk**(bob_address)
+    AB -> W_A: bob_enc_pk
+    note left W_A: The first memo <i>alice_memo</i> is for the change, \n the second one corresponds \n to the actual transfer of 1000 units of <i>asset_code</i> to Bob
+    W_A -> W_A: (transfer_tx,[alice_memo, bob_memo]):=**build_transfer_tx**(alice_address,asset_code,\n bob_address,1000)
+    W_A -> R: (transfer_tx,[alice_memo, bob_memo])
+    R -> R: b:= **create_new_block**(transfer_tx,[alice_memo, bob_memo])
+    R -> C: b
+    C -> EQS: **new_block_event**(b,[])
+    EQS -> W_A: **new_block_event**(b,[])
+    EQS -> W_B: **new_block_event**(b,[])
+    EQS -> A: **new_block_event**(b,[])
+    EQS -> F: **new_block_event**(b,[])
+
+    note left W_B: Alice receives an asset record identified by <i>asset_code</i> and amount <i>49000</i>
+    W_A -> W_A: [alice_memo] := **fetch_memos_from**(b)
+    W_A -> W_A: **update_local_state_from**(alice_memo)
+
+    note left W_B: Bob receives an asset record of identified by <i>asset_code</i> and amount <i>1000</i>
+    W_B -> W_B: [bob_memo] := **fetch_memos_from**(b)
+    W_B -> W_B: **update_local_state_from**(bob_memo)
+
+    note left A: The Auditor processes the audit memos. \n Due to the viewing policy the auditor obtains both asset records from Alice and Bob
+    A -> A: **get_and_store_info_from_txs**(b)
+
+end group
+
+
+@enduml