docs(cketh/ckerc20): update docs with new helper smart contract addre…

…ss (#2759) The new helper smart contract supporting subaccounts and deposit of both ETH and ERC-20 was deployed at the following address: 1. For Sepolia: [0x2D39863d30716aaf2B7fFFd85Dd03Dda2BFC2E38](https://sepolia.etherscan.io/address/0x2D39863d30716aaf2B7fFFd85Dd03Dda2BFC2E38). 2. For Ethereum Mainnet: [0x18901044688D3756C35Ed2b36D93e6a5B8e00E68](https://etherscan.io/address/0x18901044688d3756c35ed2b36d93e6a5b8e00e68). The docs were updated to only mention those new contracts, since the previous ones are deprecated. --------- Co-authored-by: Paul Liu <[email protected]> Co-authored-by: Thomas Locher <[email protected]>
dfinity · Nov 28, 2024 · a31f1db · a31f1db
1 parent 2d8611e
commit a31f1db
Show file tree

Hide file tree

Showing 2 changed files with 66 additions and 14 deletions.
diff --git a/rs/ethereum/cketh/docs/ckerc20.adoc b/rs/ethereum/cketh/docs/ckerc20.adoc
@@ -6,19 +6,62 @@ NOTE: An ERC-20 token denotes a fungible token on the Ethereum blockchain that f
 
 == Supported ERC-20 tokens
 
+NOTE: For the most up-to-date list of supported ERC-20 tokens, see `supported_ckerc20_tokens` when calling `get_minter_info` on the minter.
+
+=== Ethereum Mainnet
+
 |===
-|Ethereum Chain | ERC-20 token symbol | ERC-20 smart contract address
+| ERC-20 token symbol | ERC-20 smart contract address
+
+|EURC
+|https://etherscan.io/token/0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c[0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c]
+
+|LINK
+|https://etherscan.io/token/0x514910771AF9Ca656af840dff83E8264EcF986CA[0x514910771AF9Ca656af840dff83E8264EcF986CA]
+
+|OCT
+|https://etherscan.io/token/0xF5cFBC74057C610c8EF151A439252680AC68c6DC[0xF5cFBC74057C610c8EF151A439252680AC68c6DC]
+
+|PEPE
+|https://etherscan.io/token/0x6982508145454Ce325dDbE47a25d4ec3d2311933[0x6982508145454Ce325dDbE47a25d4ec3d2311933]
+
+|SHIB
+|https://etherscan.io/token/0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE[0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE]
+
+|UNI
+|https://etherscan.io/token/0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984[0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984]
 
-|link:https://github.com/ethereum-lists/chains/blob/master/_data/chains/eip155-1.json[Ethereum Mainnet]
 |USDC
 |https://etherscan.io/token/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48[0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48]
 
-|link:https://github.com/ethereum-lists/chains/blob/master/_data/chains/eip155-11155111.json[Ethereum Testnet Sepolia]
+|USDT
+|https://etherscan.io/token/0xdAC17F958D2ee523a2206206994597C13D831ec7[0xdAC17F958D2ee523a2206206994597C13D831ec7]
+
+|WBTC
+|https://etherscan.io/token/0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599[0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599]
+
+|wstETH
+|https://etherscan.io/token/0x7f39C581F595B53c5cb19bD0b3f8dA6c935E2Ca0[0x7f39C581F595B53c5cb19bD0b3f8dA6c935E2Ca0]
+
+|XAUt
+|https://etherscan.io/token/0x68749665FF8D2d112Fa859AA293F07A622782F38[0x68749665FF8D2d112Fa859AA293F07A622782F38]
+|===
+
+=== Ethereum Testnet Sepolia
+
+|===
+| ERC-20 token symbol | ERC-20 smart contract address
+
+|(Sepolia) LINK
+|https://sepolia.etherscan.io/address/0x779877A7B0D9E8603169DdbD7836e478b4624789[0x779877A7B0D9E8603169DdbD7836e478b4624789]
+
+|(Sepolia) PEPE
+|https://sepolia.etherscan.io/address/0x560eF9F39E4B08f9693987cad307f6FBfd97B2F6[0x560eF9F39E4B08f9693987cad307f6FBfd97B2F6]
+
 |(Sepolia) USDC
 |https://sepolia.etherscan.io/address/0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238[0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238]
 |===
 
-
 == Testing with Sepolia
 
 Another instance of the minter and of the ledger are deployed that target specifically the link:https://moralis.io/sepolia-testnet-guide-what-is-the-sepolia-testnet/[Sepolia] Ethereum testnet.
@@ -31,13 +74,13 @@ You can use one of the numerous link:https://sepoliafaucet.com/[Sepolia Faucet]
 |Ethereum Chain |ckERC20 helper smart contract |Minter dashboard|Ledger|`dfx` commands in
 
 |link:https://github.com/ethereum-lists/chains/blob/master/_data/chains/eip155-1.json[Ethereum Mainnet]
-|link:https://etherscan.io/address/0x6abda0438307733fc299e9c229fd3cc074bd8cc0[0x6abDA0438307733FC299e9C229FD3cc074bD8cC0]
+|link:https://etherscan.io/address/0x18901044688D3756C35Ed2b36D93e6a5B8e00E68[0x18901044688D3756C35Ed2b36D93e6a5B8e00E68]
 |link:https://sv3dd-oaaaa-aaaar-qacoa-cai.raw.icp0.io/dashboard[ckETH minter]
 |link:https://dashboard.internetcomputer.org/canister/ss2fx-dyaaa-aaaar-qacoq-cai[ckETH ledger]
 | `ic/rs/ethereum/cketh/mainnet`
 
 |link:https://github.com/ethereum-lists/chains/blob/master/_data/chains/eip155-11155111.json[Ethereum Testnet Sepolia]
-|link:https://sepolia.etherscan.io/address/0x674Cdbe64Df412DA9bAb1596e00c1520979B5A23[0x674Cdbe64Df412DA9bAb1596e00c1520979B5A23]
+|link:https://sepolia.etherscan.io/address/0x2D39863d30716aaf2B7fFFd85Dd03Dda2BFC2E38[0x2D39863d30716aaf2B7fFFd85Dd03Dda2BFC2E38]
 |link:https://jzenf-aiaaa-aaaar-qaa7q-cai.raw.icp0.io/dashboard[ckSepoliaETH minter]
 |link:https://dashboard.internetcomputer.org/canister/apia6-jaaaa-aaaar-qabma-cai[ckSepoliaETH ledger]
 | `ic/rs/ethereum/cketh/testnet`
@@ -117,20 +160,22 @@ Refer to xref:cketh.adoc#deposit_eth_to_cketh[Deposit: ETH to ckETH] to see othe
 The ERC-20 -> ckERC-20 flow involves the following steps:
 
 . The user submits an Ethereum transaction calling the `approve` function of the ERC-20 smart contract to allow the helper smart contract address to use some of the user’s funds. Depending on the amount specified, additional deposits may not need to be approved beforehand. The `approve` function can be invoked directly on the contract's Etherscan page after connecting any of Web3-capable wallets.
-. The user calls the link:https://etherscan.io/address/0x6abda0438307733fc299e9c229fd3cc074bd8cc0#writeContract[minter helper contract] `deposit` method of the helper smart contract (just as `approve` this method can be called from contract's Etherscan page) specifying
+. The user calls the link:https://etherscan.io/address/0x18901044688D3756C35Ed2b36D93e6a5B8e00E68#writeContract[minter helper contract] `depositErc20` method of the helper smart contract (just as `approve` this method can be called from contract's Etherscan page) specifying
 .. The ERC-20 smart contract address. This identifies the ERC-20 token being deposited.
 .. The amount of ERC-20 tokens being deposited.
-.. The IC principal to which the amount of ckERC-20 should be minted.
+.. The IC principal encoded as a `bytes32`.
+.. The IC ledger subaccount (use `0x` for the default subaccount). The IC principal together with the IC ledger subaccount uniquely identify an IC ledger account to which the amount of ckERC-20 should be minted.
 . The helper smart contract does the following steps within the *same* Ethereum transaction
 .. Call `transferFrom` on the ERC-20 smart contract to transfer the given amount of ERC-20 tokens from the user’s address to the minter’s address. (This requires that the smart contract’s address was previously approved as in step 2).
-.. Emits the `ReceiveErc20(address,address,uint,bytes32)` event
+.. Emits the `ReceivedEthOrErc20(address,address,uint,bytes32,bytes32)` event
 ... The first `address` argument is the ERC-20 smart contract Ethereum address.
 ... The second `address` argument is the source Ethereum address.
 ... The `uint` argument is the deposit value.
-... The `bytes32` argument encodes the receiver of ckERC20 on the IC.
+... The first `bytes32` argument encodes the IC principal.
+... The second `bytes32` argument encodes the ledger subaccount. The principal and subaccount together identify the receiver of ckERC20 on the IC.
 . The scrapping of the logs will be done as in ckETH, meaning that ckETH minter executes the following steps on a timer:
 .. Query the latest finalized block number using the `eth_getBlockByNumber` RPC endpoint. If the finalized block number hasn't changed since the last timer execution, skip the rest of the timer logic.
-.. Use the `eth_getLogs` RPC endpoint to fetch the helper smart contract logs from the previous finalized block number to the block number obtained at the previous step. The response is an array of events, where each event includes in particular the transaction hash `transactionHash` and the log entry index `logIndex`. Parse `ReceiveEth` events contained in the logs.
+.. Use the `eth_getLogs` RPC endpoint to fetch the helper smart contract logs from the previous finalized block number to the block number obtained in the previous step. The response is an array of events, where each event includes in particular the transaction hash `transactionHash` and the log entry index `logIndex`. Parse `ReceivedEthOrErc20` events contained in the logs.
 .. For each new event, if the `transactionHash` was not seen before (minter keeps track of minted transactions), check that the sender of the transaction is not on the blocklist and mint ckERC20 and include the transaction hash and the log entry index in the ckERC-20 mint transaction memo (ICRC-1 ledger feature). Add the `transactionHash` to the list of seen transactions kept by the minter. If the sender of the transaction was a blocked address, then the minter does not mint ckERC20, but still marks the transaction hash as seen.
 
 
@@ -211,6 +256,7 @@ dfx canister --network ic call CKERC20_LEDGER icrc2_approve "(record { spender =
 .. the ERC-20 token identified by the ledger id of that token,
 .. the desired withdrawal amount in the smallest unit of that token (e.g., 1 USDC = 1_000_000 USDC cents),
 .. the Ethereum destination address.
+.. optionally, from which subaccounts the ckETH for the transaction fee and the ckERC20 for the withdrawal should be burned. They do not need to be the same subaccount.
 --
 +
 [source,shell]

diff --git a/rs/ethereum/cketh/docs/cketh.adoc b/rs/ethereum/cketh/docs/cketh.adoc
@@ -17,13 +17,13 @@ You can use one of the numerous link:https://sepoliafaucet.com/[Sepolia Faucet]
 |Ethereum Chain |ckETH helper smart contract |Minter dashboard|Ledger|`dfx` commands in
 
 |link:https://github.com/ethereum-lists/chains/blob/master/_data/chains/eip155-1.json[Ethereum Mainnet]
-|link:https://etherscan.io/address/0x7574eB42cA208A4f6960ECCAfDF186D627dCC175[0x7574eB42cA208A4f6960ECCAfDF186D627dCC175]
+|link:https://etherscan.io/address/0x18901044688D3756C35Ed2b36D93e6a5B8e00E68[0x18901044688D3756C35Ed2b36D93e6a5B8e00E68]
 |link:https://sv3dd-oaaaa-aaaar-qacoa-cai.raw.icp0.io/dashboard[ckETH minter]
 |link:https://dashboard.internetcomputer.org/canister/ss2fx-dyaaa-aaaar-qacoq-cai[ckETH ledger]
 | `ic/rs/ethereum/cketh/mainnet`
 
 |link:https://github.com/ethereum-lists/chains/blob/master/_data/chains/eip155-11155111.json[Ethereum Testnet Sepolia]
-|link:https://sepolia.etherscan.io/address/0xb44B5e756A894775FC32EDdf3314Bb1B1944dC34[0xb44B5e756A894775FC32EDdf3314Bb1B1944dC34]
+|link:https://sepolia.etherscan.io/address/0x2D39863d30716aaf2B7fFFd85Dd03Dda2BFC2E38[0x2D39863d30716aaf2B7fFFd85Dd03Dda2BFC2E38]
 |link:https://jzenf-aiaaa-aaaar-qaa7q-cai.raw.icp0.io/dashboard[ckSepoliaETH minter]
 |link:https://dashboard.internetcomputer.org/canister/apia6-jaaaa-aaaar-qabma-cai[ckSepoliaETH ledger]
 | `ic/rs/ethereum/cketh/testnet`
@@ -106,7 +106,13 @@ bazel run //rs/ethereum/cketh/minter:principal_to_hex -- $(dfx identity get-prin
 ----
 ====
 
-Call the link:https://etherscan.io/address/0x7574eB42cA208A4f6960ECCAfDF186D627dCC175#writeContract[minter helper contract] `deposit` function with your principal encoded and the amount as parameters.
+Call the link:https://etherscan.io/address/0x18901044688D3756C35Ed2b36D93e6a5B8e00E68#writeContract[minter helper contract] `depositEth` function with your principal encoded and the amount as parameters.
+
+Call the link:https://etherscan.io/address/0x18901044688D3756C35Ed2b36D93e6a5B8e00E68#writeContract[minter helper contract] `depositEth` method of the helper smart contract (can be called from the contract's Etherscan page) specifying
+
+. The amount of ETH being deposited.
+. The IC principal encoded as a `bytes32`.
+. The IC ledger subaccount (use `0x` for the default subaccount). The IC principal together with the IC ledger subaccount uniquely identify an IC ledger account to which the amount of ckERC-20 should be minted.
 
 [WARNING]
 ====