From 924572b650bd689d434550a8b193d076f22a2210 Mon Sep 17 00:00:00 2001 From: gfletcher-cll Date: Wed, 15 Jan 2025 15:42:25 -0800 Subject: [PATCH] DOC-684 Update sections for 1.5.0 token pools to discuss limitations for decimals --- .../ccip/concepts/cross-chain-tokens.mdx | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/src/content/ccip/concepts/cross-chain-tokens.mdx b/src/content/ccip/concepts/cross-chain-tokens.mdx index ad4ea52facb..d2edecb1720 100644 --- 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
• Receive on B: 1.123456

• **Lost**: 0.000000789123 | • Burn/mint: Tokens permanently burned on Blockchain A
• Lock/release: Tokens locked in pool on Blockchain A | +| B → A | • Send from B: 1.123456
• Receive on A: 1.123456000000

• **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.