Merge branch 'leo-cketh-testnet-readme' into 'master'

docs(cketh): Add a readme to testnet Adds a file that describes the interactions and the commands to use with the ckSepoliaETH minter. See merge request dfinity-lab/public/ic!15008
dfinity · Sep 27, 2023 · 1b9d032 · 1b9d032
2 parents 61cdd55 + 0ba28d4
commit 1b9d032
Show file tree

Hide file tree

Showing 2 changed files with 93 additions and 2 deletions.
diff --git a/rs/ethereum/cketh/minter/README.md b/rs/ethereum/cketh/minter/README.md
@@ -21,7 +21,7 @@ dfx deploy minter --argument '(variant {InitArg = record { ethereum_network = va
 ## Converting ETH to ckETH
 
 ckETH deposits require calling a smart contract on the Ethereum chain and passing your principal as a `bytes32` array.
-The `principal-to-hex` binary is an utility that lets you convert a principal to the smart contract argument.
+The `principal-to-hex` binary is a utility that lets you convert a principal to the smart contract argument.
 
 ```shell
 cargo run --bin cketh-principal-to-hex $(dfx identity get-principal)
@@ -44,5 +44,5 @@ dfx canister call ledger icrc2_approve 'record {spender = record { owner = princ
 The specified amount for the withdrawal must not be greater than the approved amount.
 
 ```shell
-dfx canister call minter withdraw '(SMALL_AMOUNT_WEI, "YOUR_ETH_ADDRESS")
+dfx canister call minter withdraw_eth '(SMALL_AMOUNT_WEI, "YOUR_ETH_ADDRESS")
 ```
diff --git a/rs/ethereum/cketh/testnet/README.adoc b/rs/ethereum/cketh/testnet/README.adoc
@@ -0,0 +1,91 @@
+= The ckSepoliaEth Minter Canister +
+
+A demonstration of the interactions described in this file is available link:https://www.youtube.com/watch?v=y_2im2V66k0[here].
+
+== Feedback
+We would greatly appreciate any feedback you may have. Please feel free to reach out by leaving a comment in this link:https://forum.dfinity.org/t/cketh-a-canister-issued-ether-twin-token-on-the-ic/22819/1[forum post].
+
+== Deposit: SepoliaETH to ckSepoliaETH
+```
+ ┌────┐               ┌───────────────┐             ┌──────┐
+ │User│               │Helper Contract│             │Minter│
+ └─┬──┘               └───────┬───────┘             └──┬───┘
+   │                          │                        │    
+   │deposit(amount, principal)│                        │    
+   │─────────────────────────>│                        │    
+   │                          │                        │    
+   │                          │       get_events       │    
+   │                          │<───────────────────────│    
+   │                          │                        │    
+   │                          │Events(amout, principal)│    
+   │                          │───────────────────────>│    
+   │                          │                        │    
+   │              mint(amout, principal)               │    
+   │<──────────────────────────────────────────────────│    
+ ┌─┴──┐               ┌───────┴───────┐             ┌──┴───┐
+ │User│               │Helper Contract│             │Minter│
+ └────┘               └───────────────┘             └──────┘
+```
+Converting SepoliaETH into ckSepoliaETH requires a call to a smart contract on the Sepolia Ethereum testnet and passing your principal as argument, in the form of a `bytes32` array.
+The simplest way to convert your principal to the smart contract argument is to use the link:https://jzenf-aiaaa-aaaar-qaa7q-cai.raw.icp0.io/dashboard[minter dashboard].
+Another way is to use the `principal-to-hex` utility.
+
+```shell
+cargo run --bin cketh-principal-to-hex $(dfx identity get-principal)
+```
+
+```shell
+bazel run //rs/ethereum/cketh/minter:principal_to_hex -- $(dfx identity get-principal)
+```
+
+Call the link:https://sepolia.etherscan.io/address/0xb44B5e756A894775FC32EDdf3314Bb1B1944dC34#writeContract[minter helper contract] `deposit` function with your principal encoded and the amount as parameters.
+
+WARNING: It's critical that the encoded IC principal is correct otherwise the funds will be lost.
+
+Current sepolia helper contract address: `0xb44B5e756A894775FC32EDdf3314Bb1B1944dC34`.
+
+
+== Withdrawal: ckSepoliaETH to SepoliaETH
+
+```
+ ┌────┐                       ┌──────┐        ┌──────┐                                           ┌────────────────┐
+ │User│                       │Ledger│        │Minter│                                           │Ethereum Network│
+ └─┬──┘                       └──┬───┘        └──┬───┘                                           └───────┬────────┘
+   │                             │               │                                                       │         
+   │icrc2_approve(minter, amount)│               │                                                       │         
+   │────────────────────────────>│               │                                                       │         
+   │                             │               │                                                       │         
+   │withdraw_eth(destination_eth_address, amount)│                                                       │         
+   │────────────────────────────────────────────>│                                                       │         
+   │                             │               │                                                       │         
+   │                             │               │eth_sendRawTransaction(destination_eth_address, amount)│         
+   │                             │               │──────────────────────────────────────────────────────>│         
+ ┌─┴──┐                       ┌──┴───┐        ┌──┴───┐                                           ┌───────┴────────┐
+ │User│                       │Ledger│        │Minter│                                           │Ethereum Network│
+ └────┘                       └──────┘        └──────┘                                           └────────────────┘
+```
+
+The first time a user wants to withdraw some ckSepoliaETH, two steps are needed:
+
+1. Approve the minter's principal on the ledger for the desired amount.
+2. Call the minter to make a withdrawal for the desired amount. 
+
+Note that the transaction will be made at the cost of the beneficiary meaning that the resulting received amount
+will be less than the specified withdrawal amount. 
+
+The exact fee deducted depends on the dynamic Ethereum transaction fees used at the time the transaction was created.
+Additional withdrawals could be made as long as the allowance from step 1 was not exhausted or did not time out.
+
+=== Approving the Minter
+
+```shell
+dfx canister --network ic call ledger icrc2_approve "(record { spender = record { owner = principal \"$(dfx canister id minter --network ic)\" }; amount = LARGE_AMOUNT_WEI })"
+```
+
+=== Withdrawing
+
+The specified amount for the withdrawal must not be greater than the approved amount.
+
+```shell
+dfx canister --network ic call minter withdraw_eth '(SMALL_AMOUNT_WEI, "YOUR_ETH_ADDRESS")'
+```