ICCT Course: Add Scaling Decimals Chapter (#180)

Author: owenwahlgren

content/course/interchain-token-transfer/14-scaling-decimals/01-math-example.mdx

@@ -0,0 +1,56 @@
+---
+title: Scaling with TokenRemote
+description: Learn how to handle token scaling with TokenRemote contracts when bridging assets with different decimal systems.
+updated: 2024-10-04
+authors: [owenwahlgren]
+icon: Calculator
+---
+
+## Math Example
+
+Token scaling is a crucial part of cross-chain token transfers, especially when dealing with varying decimal denominations between the home and remote assets. This chapter will provide a math example to demonstrate how the scaling works with `TokenRemote` contracts.
+
+In this example, let's assume we are bridging an ERC-20 token from a home chain where the token uses 6 decimal places to a remote chain as the native token that uses 18 decimal places (e.g., USDC on Avalanche). 
+
+The key variables here are:
+- `_homeTokenDecimals = 6`
+- `_tokenDecimals = 18`
+- `_tokenMultiplier` is calculated as:
+
+<Mermaid chart={`
+sequenceDiagram
+    participant Home as TokenHome.sol (_homeTokenDecimals)
+    participant Remote as TokenRemote.sol (_tokenDecimals)
+    participant Multiplier as Token Multiplier (_tokenMultiplier)
+    
+    Home->>Remote: Calculate _tokenDecimals - _homeTokenDecimals
+    Remote->>Multiplier: 18 - 6 = 12
+    Multiplier-->>Multiplier: 10^12
+`} />
+
+This multiplier helps scale the token amounts when transferring between chains.
+
+### Scenario 1: Transferring from Home (6 decimals) to Remote (18 decimals)
+
+When transferring tokens from the home chain (6 decimals) to the remote chain (18 decimals), the token amount is multiplied by `_tokenMultiplier` to normalize the denomination. If `multiplyOnRemote = true`, we perform the following:
+
+For example, if we transfer **100 USDC** (which is represented as `100 × 10^6` in the 6-decimal system), it will be scaled as follows on the remote chain:
+
+```
+100 × 10^6 × 10^{12} = 100 × 10^{18}
+```
+Thus, the value on the remote chain would be 100 × 10^{18}, equivalent to 100 USDC in 18 decimals.
+
+### Scenario 2: Transferring from Remote (18 decimals) to Home (6 decimals)
+
+When transferring tokens back from the remote chain (18 decimals) to the home chain (6 decimals), the token amount is divided by `_tokenMultiplier`. If `multiplyOnRemote = true`, the reverse scaling applies:
+
+For example, transferring `100 × 10^{18}` (which is 100 USDC in the 18-decimal system) back to the home chain would scale down:
+
+```
+100 × 10^{18} ÷ 10^{12} = 100 × 10^6
+```
+
+This results in 100 × 10^6 USDC, which correctly represents 100 USDC in the 6-decimal system.
+
+By applying this multiplier, tokens retain their value across chains with different decimal systems.

content/course/interchain-token-transfer/14-scaling-decimals/02-example.mdx

@@ -0,0 +1,129 @@
+---
+title: Example USDC as Native Token (DIY)
+description: Learn how to transfer USDC to a new Avalanche L1 and use it as a native token via ICTT.
+updated: 2024-09-03
+authors: [owenwahlgren]
+icon: Terminal
+---
+import { Step, Steps } from 'fumadocs-ui/components/steps';
+
+In this section, you will learn how to transfer USDC from Avalanche’s C-Chain to a new Avalanche L1 using Interchain Token Transfers (ICTT) and set it up to act as the **native token** on the new L1. This guide will take you through the steps of configuring a local network environment, deploying the necessary contracts, and transferring tokens.
+
+
+<Steps>
+<Step>
+### Create a new blockchain and Deploy on Local Network
+
+Use the **Avalanche CLI** to create a new blockchain where you will deploy USDC as the native token.
+
+
+```bash
+avalanche blockchain create myblockchain  
+```
+```bash
+avalanche blockchain deploy myblockchain
+```
+</Step>
+<Step>
+### Acquire USDC On Fuji C-Chain
+
+The address for USDC on Fuji C-Chain is [`0x5425890298aed601595a70ab815c96711a31bc65`](https://testnet.snowtrace.io/token/0x5425890298aed601595a70ab815c96711a31bc65).
+For convience we have already deployed a `TokenHome` to the C-Chain for USDC with the address [`0x546526F786115af1FE7c11aa8Ac5682b8c181E3A`](https://testnet.snowtrace.io/address/0x546526F786115af1FE7c11aa8Ac5682b8c181E3A)
+
+You can use the [Core Faucet to get some USDC](https://core.app/en/tools/testnet-faucet/?subnet=c&token=usdcc) on Fuji. 
+```bash
+export USDC=0x5425890298aed601595a70ab815c96711a31bc65
+export USDC_HOME_C_CHAIN=0x546526F786115af1FE7c11aa8Ac5682b8c181E3A
+```
+</Step>
+<Step>
+### Deploy Interchain Token Transfer Contracts
+Set up the remote transferer contracts for transferring tokens between the C-Chain and the newly created L1.
+   
+- `NativeTokenRemote` Contract on `myblockchain` 
+```bash 
+forge create --rpc-url myblockchain --private-key $PK lib/avalanche-interchain-token-transfer/contracts/src/TokenRemote/NativeTokenRemote.sol:NativeTokenRemote --constructor-args "($TELEPORTER_REGISTRY_L1, $FUNDED_ADDRESS, $C_CHAIN_BLOCKCHAIN_ID_HEX, $USDC_HOME_C_CHAIN, 6)" "USDC" 100000000000000000000 0
+```
+
+_Note: When deploying the `NativeTokenRemote` contract on the L1, ensure that the **initial amount** matches the native token amount that was minted when the blockchain was created. This ensures consistency between the native token supply and the remote token counterpart._
+
+```bash
+export NATIVE_TOKEN_REMOTE_L1="Deployed To Address"
+```
+</Step>
+<Step>
+### Granting Native Minting Rights to NativeTokenRemote Contract
+To ensure that the `NativeTokenRemote` contract can mint native tokens on the L1 when USDC tokens are transferred from the `C-Chain`, the contract must be granted **minting rights**. This is done by adding the `NativeTokenRemote contract` address to the `Native Minter Precompile`.
+
+1. You will need to interact with the `Native Minter Precompile`, which resides at a fixed address on all Avalanche L1s:  
+**Native Minter Precompile Address**: `0x0200000000000000000000000000000000000001`
+     
+2. Use the following command to grant the `NativeTokenRemote` contract minting rights by setting it as an **enabled** address on the Native Minter Precompile:
+  
+```bash
+cast send --rpc-url myblockchain --private-key $PK 0x0200000000000000000000000000000000000001 "setEnabled(address)" $NATIVE_TOKEN_REMOTE_L1
+```
+
+- `$NATIVE_TOKEN_REMOTE_L1`: The deployed address of the `NativeTokenRemote` contract on your L1.
+
+Once this step is completed, the `NativeTokenRemote` contract will have the necessary permissions to mint native tokens when USDC tokens are transferred from the C-Chain.
+</Step>
+<Step>
+### Register Remote Token with Home Transferer
+Register the remote token on the home chain so that it recognizes the transferer contracts.
+
+```bash 
+cast send --rpc-url myblockchain --private-key $PK $NATIVE_TOKEN_REMOTE_L1 "registerWithHome((address, uint256))" "(0x0000000000000000000000000000000000000000, 0)"
+```
+</Step>
+<Step>
+### Collateralize and Transfer Tokens
+Add collateral to the transferer contract on the home chain, and then send the USDC tokens across chains.
+
+<Accordions>
+<Accordion title="What is Collateral?">
+Collateral in this context refers to the amount of the token that is locked in the `Home Transferer contract` on the source chain (`C-Chain`) to back the value of the token on the destination chain (`myblockchain`). This ensures that for every token minted on the remote chain, there’s an equivalent token locked as collateral on the home chain.
+</Accordion>
+<Accordion title="Why is Collateral Important?">
+Collateralization ensures that the total supply of the token remains consistent across both chains. When tokens are sent from the `home chain`, they are locked as collateral, and a corresponding number of tokens is minted on the remote chain. If tokens are sent back to the home chain, the collateral is unlocked, and the minted tokens on the remote chain are burned.
+</Accordion>
+</Accordions>
+
+- **Approve Tokens for Transfer**  
+Approve a certain number of tokens to be used by the Home Transferer. 
+
+```bash  
+cast send --rpc-url local-c --private-key $PK $USDC "approve(address, uint256)" $USDC_HOME_C_CHAIN 2000000000000000000000
+```
+
+- **Add Collateral and Send Tokens**  
+Add collateral to the transferer contract.
+```bash 
+cast send --rpc-url local-c --private-key $PK $USDC_HOME_C_CHAIN "addCollateral(bytes32, address, uint256)" $L1_BLOCKCHAIN_ID_HEX $NATIVE_TOKEN_REMOTE_L1 100000000000000000000
+```
+You can also confirm whether the Transferer is collateralized now by running the below command:
+
+```bash
+cast call --rpc-url myblockchain $NATIVE_TOKEN_REMOTE_L1 "isCollateralized()(bool)"
+```
+Send tokens to the L1
+```bash 
+cast send --rpc-url local-c --private-key $PK $USDC_HOME_C_CHAIN "send((bytes32, address, address, address, uint256, uint256, uint256, address), uint256)" "(${L1_BLOCKCHAIN_ID_HEX}, ${NATIVE_TOKEN_REMOTE_L1}, ${FUNDED_ADDRESS}, ${USDC}, 0, 0, 250000, 0x0000000000000000000000000000000000000000)" 1000000000000000000000
+```
+</Step>
+
+<Step>
+Check Balance
+```bash
+cast balance --rpc-url myblockchain $FUNDED_ADDRESS
+```
+</Step>
+</Steps>
+
+---
+
+### Conclusion
+
+Follow the steps above to transfer a USDC token from the C-Chain to your custom Avalanche L1 and use it as the native token. This exercise will demonstrate how Avalanche’s **Interchain Token Transfer (ICTT)** system works, ensuring that tokens are properly locked, transferred, and minted across multiple chains.
+
+For more detailed information, refer to the [official Avalanche ICTT documentation](/course/interchain-token-transfer).

content/course/interchain-token-transfer/meta.json

@@ -22,7 +22,9 @@
     "---Send and Call---",
     "...12-send-and-call",
     "---Cross-Chain Token Swaps---",
-    "...13-cross-chain-token-swaps"
+    "...13-cross-chain-token-swaps",
+    "---Scaling Token Decimals---",
+    "...14-scaling-decimals"
   ]
 }