diff --git a/doc/internal/.gitignore b/doc/internal/.gitignore index e33609d2..756b22fa 100644 --- a/doc/internal/.gitignore +++ b/doc/internal/.gitignore @@ -1 +1 @@ -*.png +*.svg diff --git a/doc/internal/gen_png.sh b/doc/internal/gen_png.sh deleted file mode 100755 index cc47e22d..00000000 --- a/doc/internal/gen_png.sh +++ /dev/null @@ -1,8 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -rm -f *.png -for file in *.puml; do - echo $file - plantuml $file -done diff --git a/doc/internal/gen_svg.sh b/doc/internal/gen_svg.sh new file mode 100755 index 00000000..6cee04d8 --- /dev/null +++ b/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 diff --git a/doc/internal/global_seq_diag/erc20.puml b/doc/internal/global_seq_diag/erc20.puml new file mode 100644 index 00000000..4bb843bd --- /dev/null +++ b/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 diff --git a/doc/internal/global_seq_diag/freeze.puml b/doc/internal/global_seq_diag/freeze.puml new file mode 100644 index 00000000..c67503f9 --- /dev/null +++ b/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: **Error** + +end group + +@enduml diff --git a/doc/internal/global_seq_diag/mint.puml b/doc/internal/global_seq_diag/mint.puml new file mode 100644 index 00000000..d8509c8b --- /dev/null +++ b/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 diff --git a/doc/internal/global_seq_diag/transfer.puml b/doc/internal/global_seq_diag/transfer.puml new file mode 100644 index 00000000..67214052 --- /dev/null +++ b/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 alice_memo is for the change, \n the second one corresponds \n to the actual transfer of 1000 units of asset_code 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 asset_code and amount 49000 + 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 asset_code and amount 1000 + 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