DOC-684

Update sections for 1.5.0 token pools to discuss limitations for decimals
smartcontractkit · Jan 15, 2025 · 924572b · 924572b
1 parent ea4ff4b
commit 924572b
Showing 1 changed file with 19 additions and 0 deletions.
diff --git a/src/content/ccip/concepts/cross-chain-tokens.mdx b/src/content/ccip/concepts/cross-chain-tokens.mdx
@@ -156,6 +156,25 @@ On the **destination blockchain**, the CCIP OffRamp contract performs three key
 
 #### Token Decimal Handling
 
+**v1.5.0**
+
+Token pools on **v1.5.0** do not support tokens with different decimal places across blockchains. When transferring a token between blockchains with differing decimal places, the token loses precision resulting in different amounts of tokens between the source and destination blockchain.  
+
+Consider a token developer who deployed their token across two blockchains with different decimal configurations:
+
+- Blockchain A: Pool with 12 decimals
+- Blockchain B: Pool with 6 decimals
+
+| Transfer Path | Example                                                                                                       | Impact                                                                                                           |
+| ------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| A → B         | • Send from A: 1.123456789123<br/>• Receive on B: 1.123456<br/><br/>• **Lost**: 0.000000789123 | • Burn/mint: Tokens permanently burned on Blockchain A<br/>• Lock/release: Tokens locked in pool on Blockchain A |
+| B → A         | • Send from B: 1.123456<br/>• Receive on A: 1.123456000000<br/><br/>• **Gained**: 0.0 | • No precision loss                                                                                              |
+
+
+We highly recommend [upgrading to v1.5.1](#upgrading-from-v150) to leverage the native support for token decimal handling. If using v1.5.0, please make sure to [configure a custom v1.5.0 token pool](#custom-token-pools).   
+
+**v1.5.1**
+
 Starting from **v1.5.1**, token pools support tokens with different decimal places across blockchains. This feature can impact the total number of tokens in circulation because tokens locked/burned on the source chain might result in a smaller number of tokens minted/released on the destination chain due to decimal rounding.
 
 <Aside type="caution" title="Impact on Token Supply">